node-webhooks

    1.4.2 • Public • Published

    node-webhooks Build Status NPM Version Coverage Status JavaScript Style Guide Dependency Status Patreon donate button

    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

    Install

    npm i node-webhooks

    DownloadsWeekly Downloads

    1,361

    Version

    1.4.2

    License

    MIT

    Unpacked Size

    35.4 kB

    Total Files

    6

    Last publish

    Collaborators

    • roccomuso