This revision made November 07, 2009 09:23, by kenaiadmin
« earlier revision revert to this later revision »

» Netbeans.org Site Tools Help - Home Page

About Web Hooks

Web hooks are an advanced feature that provide a way for you to customize handling of data that results from changes in your netbeans.org projects. You do this by specifying an HTTP callback URL for each project and indicating which events you're interested in. Instead of requiring your web applications to poll your netbeans.org project to see what's changed, netbeans.org web hooks send information to your callback URL as events occur in your projects, such as a commit to one of your code repositories.

You process the data on a web page of your choosing. The page must accept POST requests and have code to interpret and handle the JSON (JavaScript Object Notation) payloads sent by netbeans.org. In the Web Hooks tab, you provide the URL of the web page and click the checkbox next to the features you want to track. At present, there is one feature you can track, source code repository updates.

Note: A web hook is automatically disabled after 10 failed connection attempts. After a web hook is disabled, a project administrator must change the URL to re-enable the web hook. See Web Hooks tab for more information on setting a web hook URL for a project.

Notification Format and Sample JSON Code

Web hooks are passed as the JSON-encoded body of a POST request to your hook URL. They contain the following information:

AttributeFormatDescriptionRequired
user string Username of the user responsible for the event false
project string Short name of the project affected by the event true
project_href URL Location of project resource API endpoint true
feature string Short name of the feature affected by the event false
feature_href URL Location of feature resource API endpoint false
event string Type of event which occurred ('scm', 'role', 'ticket', etc.) true
time timestamp Time at which the event occurred true
message string Additional explanatory text for the event (i.e., SCM commit message, new ticket name, etc.) false
data object Per-notification-type supplementary data about this event (see examples below) false

Here's a sample JSON payload for a web hook notification. This notification was sent after a commit to the project's git3 source repository.

   {
    "message":"[git3] SCM commit: test (username)",
    "user":"username",
    "time":"2009-04-02T17:30:50Z",
    "project":"hook-test",
    "event":"scm",
    "id":32,
    "project_href":"http://netbeans.org/api/projects/hook-test",
    "feature":"git3",
    "feature_href":"http://netbeans.org/api/projects/hook-test/features/git3",
    "data":[{
      "revision":"f7f9cd087568f0db48d8132141d798c01f6f7800",
      "message":"test",
      "changes":[["M","README.txt"]]
    }]
  } 

Sample Web Hook Handler Code: php

  <?php   
  // This example hook endpoint simply extracts the 'message' attribute of each notification
  // and stores it in a MySQL table, then lists the received hook messages when you view
  // the page. Real notification targets would likely capture additional information, such as 
  // the user responsible for the commit, and could also perform additional work such as 
  // executing an automated test suite.

  // db connection info  
  $db_name= 'hook_data';  
    
  $dbh = mysqli_connect('127.0.0.1', 'root', '');  
  $db_exists = $dbh->select_db($db_name);  
    
  // db/table setup  
  if (!$db_exists) {  
    $res = $dbh->query("CREATE DATABASE $db_name");  
    if (!$res)  
      die("could not create database");  
    $dbh->select_db($db_name);  
  }  
    
  $res = $dbh->query('DESC notifications');  
  if (!$res) {  
    $res = $dbh->query('CREATE TABLE notifications ( message VARCHAR(255) )');  
    if (!$res)  
      die("could not create database notificatiosn table");  
  }  
    
  // actual hook handling  
  if ($_SERVER['REQUEST_METHOD'] == 'POST') {  
    $raw_data = file_get_contents("php://input");  
    $hook_data = json_decode($raw_data);  
    if (!$hook_data)  
      die("could not parse hook data");  
    $message = $hook_data->message;  
    $stmt = $dbh->prepare('INSERT INTO notifications ( message ) VALUES( ? )');  
    $stmt->bind_param('s', $message);  
    $res = $stmt->execute();  
    if (!$res)  
      die("database update failed");  
  }  
    
  // history query  
  $notify_res = $dbh->query('SELECT * FROM notifications');  
  $notify_count = $notify_res->num_rows;  
  if (!$notify_count)  
    $notify_count = "no";  

  // page content
  ?><html> 
  <head> 
    <title>Notification History</title> 
  </head> 
  <body> 
    <h1>Notification History</h1> 
    <p>So far, we have received <strong><?php echo $notify_count ?></strong>
       web hook notification(s).</p> 
    <?php if($notify_count > 0) { ?> 
      <ol> 
        <?php while($row = $notify_res->fetch_array()) { ?> 
          <li><?php echo $row[0]; ?></li> 
        <?php } ?> 
      </ol> 
    <?php } ?> 
  </body> 
  </html>

Sample Web Hook Handler Code: ruby

  # This hook uses the 'sinatra', 'xmpp4r', and 'json' Ruby libraries to perform basic notification
  # of commits over Jabber. In most real-world scenarios, you would likely want to notify a list 
  # of recipients, or even use the MUC (Multi-User Chat) extension to send messages to a group
  # chat room.
  require 'rubygems'  
  require 'sinatra'  
  require 'xmpp4r'  
  require 'json'  
    
  JID = ENV['JABBER_JID'] || 'username@jabber.org'  
  PASSWORD = ENV['JABBER_PASS'] || 'password'  
    
  configure do  
    $client = Jabber::Client.new("#{JID}/commit-bot")  
    $client.connect  
    $client.auth(PASSWORD)  
  end  
    
  post '/ping' do  
    hook_data = params[:data]  
    xmpp_msg = Jabber::Message.new(JID, hook_data['message'])  
    $client.send(xmpp_msg)  
  end  

More Information on Web Hooks

See the following web sites for more information on web hooks:

Project Features

Wiki Controls

About this Project

Help for netbeans.org Site Tools was started in November 2009, is owned by kenaiadmin, and has 17 members.
By use of this website, you agree to the NetBeans Policies and Terms of Use (revision 20140418.2d69abc). © 2013, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo
 
 
Close
loading
Please Confirm
Close