Last updated November 07, 2012 19:15, by nvause
[[Home| &raquo; Project Kenai Documentation and Training]] &nbsp; &nbsp; [[Howdoi| &raquo; How Do I ...]] <h1>About Web Hooks</h1> __TOC__ Web hooks are an advanced feature that provide a way for you to customize handling of data that results from changes in your Kenai 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 Project Kenai applications to see what's changed, Project Kenai 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 Project Kenai. In the [[ManageProject#WebHooks|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 [[ManageProject#WebHooks|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: {|- border="1" |'''Attribute''' |'''Format''' |'''Description''' |'''Required''' |- valign="top" |user |string |Username of the user responsible for the event |false |- valign="top" |project |string |Short name of the project affected by the event |true |- valign="top" |project_href |URL |Location of project resource API endpoint |true |- valign="top" |feature |string |Short name of the feature affected by the event |false |- valign="top" |feature_href |URL |Location of feature resource API endpoint |false |- valign="top" |event |string |Type of event which occurred ('scm', 'role', 'ticket', etc.) |true |- valign="top" |time |timestamp |Time at which the event occurred |true |- valign="top" |message |string |Additional explanatory text for the event (i.e., SCM commit message, new ticket name, etc.) |false |- valign="top" |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":"<nowiki></nowiki>", "feature":"git3", "feature_href":"<nowiki></nowiki>", "data":[{ "revision":"f7f9cd087568f0db48d8132141d798c01f6f7800", "message":"test", "changes":<nowiki>[["M","README.txt"]]</nowiki> }] } ==Sample Web Hook Handler Code: php== <pre name="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('', '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> </pre> ==Sample Web Hook Handler Code: ruby== <pre name="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'] || '' PASSWORD = ENV['JABBER_PASS'] || 'password' configure do $client ="#{JID}/commit-bot") $client.connect $client.auth(PASSWORD) end post '/ping' do hook_data = params[:data] xmpp_msg =, hook_data['message']) $client.send(xmpp_msg) end </pre> ==More Information on Web Hooks== See the following web sites for more information on web hooks: * [ Video of Presentation by Jeff Lindsay] * [ Jeff Lindsay's Web Hooks Blog site] * [ Web Hooks Wiki] * [ Web Hooks Google Group]

Project Features

Wiki Controls

About this Project

Help for Site Tools was started in November 2009, is owned by kenaiadmin, and has 34 members.
By use of this website, you agree to the NetBeans Policies and Terms of Use (revision 20160708.bf2ac18). © 2014, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo
Please Confirm