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 = // Initialize webhooks module from on-disk databasevar 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-memorywebHooks = db: "addPost": "http://localhost:9100/posts" // just an example // sync instantation - add a new webhook called 'shortname1'webHooks // add another webHookwebHooks; // 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 webHookwebHookswebHooks // 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 = db: WEBHOOKS_DB DEBUG: true var emitter = webHooks emitter emitter
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