README

node-webhooks

What WebHooks are used for

Webhooks are "user-defined HTTP callbacks". They are usually triggered by some event, such as pushing code to a repository or a comment being posted to a blog. When that event occurs, the source site makes an HTTP request to the URI configured for the webhook. Users can configure them to cause events on one site to invoke behaviour on another. The action taken may be anything. Common uses are to trigger builds with continuous integration systems or to notify bug tracking systems. Since they use HTTP, they can be integrated into web services without adding new infrastructure.

Install

npm install node-webhooks --save

Supporting Node.js 0.12 or above.

How it works

When a webHook is triggered it will send an HTTPS POST request to the attached URLs, containing a JSON-serialized Update (the one specified when you call the trigger method).

Debug

This module makes use of the popular debug package. Use the env variable to enable debug: DEBUG=node-webhooks. To launch the example and enable debug: DEBUG=node-webhooks node example.js

Usage


// Initialize WebHooks module.
var WebHooks = require('node-webhooks')

// Initialize webhooks module from on-disk database
var webHooks = new WebHooks({
    db: './webHooksDB.json', // json file that store webhook URLs
    httpSuccessCodes: [200, 201, 202, 203, 204], //optional success http status codes
})

// Alternatively, initialize webhooks module with object; changes will only be
// made in-memory
webHooks = new WebHooks({
    db: {"addPost": ["http://localhost:9100/posts"]}, // just an example
})

// sync instantation - add a new webhook called 'shortname1'
webHooks.add('shortname1', 'http://127.0.0.1:9000/prova/other_url').then(function(){
    // done
}).catch(function(err){
    console.log(err)
})

// add another webHook
webHooks.add('shortname2', 'http://127.0.0.1:9000/prova2/').then(function(){
    // done
}).catch(function(err){
    console.log(err)
});

// remove a single url attached to the given shortname
// webHooks.remove('shortname3', 'http://127.0.0.1:9000/query/').catch(function(err){console.error(err);})

// if no url is provided, remove all the urls attached to the given shortname
// webHooks.remove('shortname3').catch(function(err){console.error(err);})

// trigger a specific webHook
webHooks.trigger('shortname1', {data: 123})
webHooks.trigger('shortname2', {data: 123456}, {header: 'header'}) // payload will be sent as POST request with JSON body (Content-Type: application/json) and custom header

Available events

We're using an event emitter library to expose request information on webHook trigger.

var webHooks = new WebHooks({
    db: WEBHOOKS_DB,
    DEBUG: true
})

var emitter = webHooks.getEmitter()

emitter.on('*.success', function (shortname, statusCode, body) {
    console.log('Success on trigger webHook' + shortname + 'with status code', statusCode, 'and body', body)
})

emitter.on('*.failure', function (shortname, statusCode, body) {
    console.error('Error on trigger webHook' + shortname + 'with status code', statusCode, 'and body', body)
})

This makes possible checking if a webHook trigger was successful or not getting request information such as status code or response body.

The format for the events is built as eventName.result. The choosen library eventemitter2 provides a lot of freedom for listening events. For example:

eventName.success
eventName.failure
eventName.*
*.success
*.*

API examples

webHooks are useful whenever you need to make sure that an external service get updates from your app. You can easily develop in your APP this kind of webHooks entry-points.

GET /api/webhook/get Return the whole webHook DB file.
GET /api/webhook/get/[WebHookShortname] Return the selected WebHook.
POST /api/webhook/add/[WebHookShortname] Add a new URL for the selected webHook. Requires JSON params:
GET /api/webhook/delete/[WebHookShortname] Remove all the urls attached to the selected webHook.
POST /api/webhook/delete/[WebHookShortname] Remove only one single url attached to the selected webHook. A json body with the url parameter is required: { "url": "http://..." }
POST /api/webhook/trigger/[WebHookShortname] Trigger a webHook. It requires a JSON body that will be turned over to the webHook URLs. You can also provide custom headers.

Author

Rocco Musolino - @roccomuso

Usage no npm install needed!