README
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