Webhooks for all.
Installation and setup are straight-forward.
npm install autohost hyped fount postal -S
var autohost = require( "autohost" );
var host;
var hyped = require( "hyped" )();
var fount = require( "fount" );
var postal = require( "postal" );
var channel = postal.channel( "eventChannel" );
fount.register( "webHookEvents", channel );
host = hyped.createHost( autohost, {
port: config.nonstop.host.port,
modules: [
"autohost-webhook"
],
fount: fount
}, function() {
host.start();
} );
See Storage API to understand how to create your own compatible storage layer.
var autohost = require( "autohost" );
var host;
var hyped = require( "hyped" )();
var fount = require( "fount" );
var postal = require( "postal" );
var channel = postal.channel( "eventChannel" );
var hooks = require( "./myHookStorage" );
fount.register( "hooks", hooks );
fount.register( "webHookEvents", channel );
host = hyped.createHost( autohost, {
port: config.nonstop.host.port,
modules: [
"autohost-webhook"
],
fount: fount
}, function() {
host.start();
} );
To call webhooks, simply send a message to the channel registered as "webHookEvents"
earlier.
// this will send the message to all registered webhooks with a subscription matching "some.event" or that have not provided an `events` filter
channel.publish( "some.event", { ... } );
When creating a web hook, please note that the headers section is the only way to support/provide authentication when calling an endpoint. It is recommended that even with HTTPS in place, your users don't provide anything other than tokens with least privilege.
Without providing a list of events that your webhook is interested in, this module will call your webhook for every event. Events support AMQP style pattern matching so if you wanted to know about every event related to a user, you could provide "user.#" to see all events under that namespace.
Both are supported. PUT requires you to provide all the hook data while PATCH supports only changing the property you need to change.
Request
GET /api/hook/:id
Response
{
"id": "",
"url": "http://the.full.url/to/call",
"method": "POST",
"headers": {
},
"events": []
}
Request
GET /api/hook/
Response
{
"hooks": [
{
"id": "",
"url": "http://the.full.url/to/call",
"method": "POST",
"headers": {
"Authorization": "Bearer a.token"
},
"events": []
},
{
"id": "",
"url": "http://the.full.url/to/call",
"method": "POST",
"headers": {
"Authorization": "Bearer a.token"
},
"events": []
}
]
}
Request
POST /api/hook/:id
{
"url": "http://the.full.url/to/call",
"method": "POST",
"headers": {
"Authorization": "Bearer a.token"
},
"events": []
}
Response
{
"id": "webhook.identifier",
"message": "Webhook webhook.identifier added successfully"
}
### Update
_Request_
`PATCH /api/hook/:id`
```json
[
{ "op": "add", "field": "events", "value": "user.#" },
{ "op": "remove", "field": "headers" },
{ "op": "change", "field": "method", "value": "PUT" },
]
Response
{
"id": "webhook.identifier",
"message": "Webhook webhook.identifier updated successfully"
}
### Replace
_Request_
`PUT /api/hook/:id`
```json
{
"url": "http://the.full.url/to/call",
"method": "POST",
"headers": {
"Authorization": "Bearer new.token"
},
"events": [ "stuff" ]
}
Response
{
"id": "webhook.identifier",
"message": "Webhook webhook.identifier replaced successfully"
}
### Remove
_Request_
`DELETE /api/hook/:id`
_Response_
```json
{
"id": "webhook.identifier",
"message": "Webhook webhook.identifier removed successfully"
}
## Hook Storage API
Each call should return a promise. The following calls must be supplied:
* add( id, hook )
* checkId( id )
* getById( id )
* getList()
* remove( id )
* update( id, hook )
The structure of the hook object follows this format:
```javascript
{
id: '', // required
url: '', // required
method: '', // required
headers: {}, // optional, content-type will always be "application/json"
events: [], // optional, list of events to subscribe to
}
Note: the id is auto-prefixed based on the authenticated user. The delimiter used to separate the user identifier from the hook id is
"::"
.