GME Webhooks

The webgme server can be configured to send out events to external agents when changes to a project in the storage is made. These events are typically related to the evolution of the model, e.g. when a commit is made or a branch hash is updated, but also include other events such as when a branch or tag is created. The design is heavily influenced by GitHub's webhooks.

Which and where to forward events are configured at a per project basis. To view/created/modify/delete web-hooks the REST-API/projects provides the necessary routes. The parameters for registering a new web-hook may look like:

{
  description: 'MyWebHook triggered on each commit.',
  events: ['COMMIT'],
  url: 'http://127.0.0.1:9000/MyWebHook'
}

The parameter events either takes an array of the events that should trigger the webhook (see list at bottom) or a string 'all' which will trigger all events.

Note that the url only needs to be accessible from the webgme server (and is typically not a public address).

Creating a basic webhook handler

In nodejs using an express server.

var PORT = 9000,
    Express = require('express'),
    bodyParser = require('body-parser');

var app = new Express();

app.use(bodyParser.json());

app.post('', function (req, res) {
    var payload = req.body;

    console.log('received payload', JSON.stringify(payload, null, 2));
    res.sendStatus(200);
});

app.listen(PORT);

console.log('Server listening at port', PORT);

Start your webgme server at say port 8888 - make sure config.webhooks.enable = true!

Registering Webhooks at Projects

To register a hook to the project guest+MyProject that will forward all events to the handler you can use the REST API or the manage_webhooks.js command line interface.

CLI

<RepoRootDir>$ node manage_webhooks.js add MyProject MyWebHook http://localhost:9000 -e all

REST API

curl -H 'Content-Type: application/json' -X PUT -d '{"description":"MyWebHook triggered on each commit.","events":"all","url":"http://127.0.0.1:9000"}' http://127.0.0.1:8888/api/projects/guest/MyProject/hooks/MyWebHook

N.B. If authentication is turned on you need to generate a token and add to the headers under Bearer <token>. An easy way to obtain a token is to login from a browser and go to /api/user/token.

Since version 2.15.0 you can also specify a range of default webhooks that are added when a project is created using the gmeConfig.

Since version 2.15.0 all webhooks are copied over from the source project to the new one when duplicating or transferring a project.

Events and Payload

When an event is dispatched from the storage all webhooks registered (and active) for the affected project gets a post request sent to them with the following payload:

payload = {
  event: 'COMMIT',
  projectId: 'guest+MyProject',
  owner: 'guest',
  projectName: 'MyProject',
  hookId: 'MyWebHook',
  data: <event dependent, see list below>
};

Event list

An object with all webhook events are available in the common constants (since v2.13.0).

var WEBHOOKS = requirejs('common/Constants').WEBHOOK_EVENTS;

'COMMIT'

Triggered on every commit to a project (with or without a branch update).

{
  "projectId": "demo+Templates",
  "commitHash": "#d8de3bdd38be13c43ea182058d397e9e28d4b4ef",
  "userId": "demo"
}

'BRANCH_HASH_UPDATED'

The branch hash, i.e. the HEAD of a branch, was updated (with or without a commit)

{
  "projectId": "demo+Templates",
  "branchName": "master",
  "newHash": "#8d7ef4b244a906e3af04a6bca7a8388cd006bae1",
  "oldHash": "#909af9a4b16944ebd955d3e20f90ba01a0eb1c3c",
  "userId": "demo"
}

'BRANCH_CREATED'

{
  "projectId": "demo+Templates",
  "branchName": "b1",
  "newHash": "#d8de3bdd38be13c43ea182058d397e9e28d4b4ef",
  "oldHash": "",
  "userId": "demo"
}

'BRANCH_DELETED'

{
  "projectId": "demo+Templates",
  "branchName": "b1",
  "newHash": "",
  "oldHash": "#d8de3bdd38be13c43ea182058d397e9e28d4b4ef",
  "userId": "demo"
}

'BRANCH_JOINED'

Triggered when a client connects to a branch.

{
  "projectId": "demo+Templates",
  "branchName": "b1",
  "userId": "demo"
}

'BRANCH_LEFT'

Triggered when a client disconnects from, or leaves, a branch.

{
  "projectId": "demo+Templates",
  "branchName": "b1",
  "userId": "demo"
}

'TAG_CREATED'

{
  "projectId": "demo+Templates",
  "tagName": "tag",
  "commitHash": "#d8de3bdd38be13c43ea182058d397e9e28d4b4ef",
  "userId": "demo"
}

'TAG_DELETED'

{
  "projectId": "demo+Templates",
  "tagName": "tag",
  "userId": "demo"
}