cool-webhooks

An outgoing webhooks library for Node.js

Installation

npm i --save cool-webhooks

Usage

const { WebhookManager } = require('cool-webhooks')
const webhooks = new WebhookManager()

Register a new webhook

// Add a new webhook
let webhookId = await webhooks.add({
    // required
    event: 'order.created',
 
    // required
    endpoint: 'http://example.com/foo',
 
    // optional method, default is POST
    method: 'POST',
 
    // optional headers
    headers: {
        authorization: 'bearer a_token'
    }
})

Trigger a webhook

const event = 'order.created'
const payload = {
    order_id: '12345'
    // ... other payload fields
}
 
const results = await webhooks.trigger(event, payload) // returns an array

Get a list of all webhooks

let registeredWebhooks = await webhooks.list() // returns an array

Find webhooks matching an event

const event = 'order.created'
 
let matched = await webhooks.find(event) // returns an array

Unregister a webhook

const webhookId = 'some-webhook-id'
 
await webhooks.remove(webhookId) // throws an error if the webhook could not be removed

Adapters

We make use of the Adapter pattern to support any storage option you may want to use (MySQL, MongoDB...etc). Currently, the default adapter is InMemoryAdapter.

Create a custom adapter

Your custom adapter must implement these methods:

const customAdapter = {
    async add(webhook) {
        // this should create a new webhook and save it
        // return the webhook ID
    },
    async remove(webhookId) {
        // Remove the webhook
    },
    async list() {
        // return an array that contains all of the registered webhooks
    },
    async find(event) {
        // return an array of webhooks matching an event
    }
}
 
const webhooks = new WebhookManager({
    adapter: customAdapter
})

Events

cool-webhooks implements an event emitter interface to which you can listen for emitted events.

The supported events are:

• webhook.added is emitted when a new webhook is registered.
• webhook.removed is emitted when a webhook is unregistered.
• webhook.success is emitted when a webhook has been triggered and succeeded.
• webhook.fail is emitted when a webhook has been triggered but failed.

Example:

webhooks.on('webhook.success', (webhook, result) => {
    console.log('webhook succeeded: ', webhook.id)
})
 
webhooks.on('webhook.fail', (webhook, result) => {
    console.log('webhook failed: ', webhook.id)
})

License

MIT