Webhooks is a simple notification pattern that works over HTTP. There is no clear standard for exactly how to implement the mechanism. At it’s simplest it allows a user to define a HTTP callback for a given hook. Whenever an event is produced for the given hook then the HTTP callback provided is called with details of the event. Many users can register for callback on the same hook. In most implementations, as well as registering for the hook itself, it is also possible to specify the set of events that the user wants to be notified about.
For IIB to interact with App Connect it will need to be setup to implement a Webhook pattern as described in this document.
This can be be done using the standard HTTP nodes provided in IIB, and an example of how to do this is given in the same repo that contains this document.
The IIB API for setting up a callback will be based on a REST model where the REST actions are made against a Webhook URL that is being served by IIB. There will be as many of these Webhook points as a message flow developer (Igor) wants to define. For example, they might choose to have a webhook for /warehouse/stock/hook and another for /crm/customer/hook.
I will use the term subscribe to mean the act of registering a callback and subscription for the object created by the subscribe action. GihHub call it a hook but that is a little confusing as for me the hook is the thing you attach to. The REST operation will then work as follows:
| REST operation | Webhook path | Description |
|---|---|---|
| POST | {IIB root}/{hookpath}/ | Create a subscription |
| GET | {IIB root}/{hookpath}/ | List subscriptions |
| GET | {IIB root}/{hookpath}/{id}/ | Get a subscription |
| PUT | {IIB root}/{hookpath}/{id}/ | Update a subscription |
| DELETE | {IIB root}/{hookpath}/{id}/ | Delete a subscription |
The webhook or subscription will not appear directly in the API so there is nothing stopping the IIB developer (Igor) adding one of the words to the path. For example they might choose: /warehouse/stock/hook or /warehouse/stock/subscribe.
When the HTTP callback is called to deliver an event a POST action is done. The content of the POST body can be any data the user wants to define for an event. It does not even have to be JSON or an XML document. The event_type is added into the http header as a custom property: X-EventType.
| POST | {IIB root}/{hookpath}/ | Create a subscription |
By POSTing to the URL for the webhook a subscription is created with the details of the callback required and the type of events that should be sent. An id is returned from the post to uniquely identify the subscription and can then be used in further REST calls to display or change the subscription.
| Name | Type | Required | Description |
|---|---|---|---|
| callback | object | yes | Structure to provide details of the HTTP callback |
| Event_types | array | no | Determines what events are to be subscribed for callback. If the parameter is missing then all events will be sent. An empty array will mean no events will be sent. |
The callback object has the following fields:
| Field | Type | Required | Description |
|---|---|---|---|
| url | string | yes | URL to callback on when an event is published. |
| secret | string | no | Secret to exchange to prove identity of event sender (not implemented yet in sample). |
The mechanism used by GitHub is to HMAC hex digest of the body, using the secret as the key and then adding the value to the HTTP header. Something like a HTTP field X-Hook-Signature.
The response will return a 201 code if the POST is successful and an object with a single id field. The id is the name of the subscription made and can be used in other REST calls to retrieve, update or delete the subscription.
Return code 404 if webhook path does not exist.
##DELETE A SUBSCRIPTION##
| DELETE | {IIB root}/{hookpath}/{id} | Delete a subscription |
Deletes the subscription defined by the path. This stops any callbacks being made to the registered HTTP callback.
Return code 204 is return if successful.
Return code 404 if id is not a valid subscription.
##LIST SUBSCRIPTIONS##
| GET | {IIB root}/{hookpath}/{id} | List subscriptions |
Lists all the current subscriptions. Returns an array of subscription objects currently subscribed.
Returns an array of the following structure:
| Field | Type | Required | Description |
|---|---|---|---|
| id | number | id for the subscription. | |
| url | string | URL to callback on when an event is published. | |
| secret | string | Secret to exchange to prove identity of event sender (not implemented yet in sample). |
Return code 200 is returned if successful with any array of all ids.
Return code 404 if id is not a valid subscription.
##GET SUBSCRIPTION##
| GET | {IIB root}/{hookpath}/{id} | Get a subscription |
Retrieves details of a particular subscription.
Returns the following properties with return code 200.
| Field | Type | Required | Description |
|---|---|---|---|
| id | number | id for the subscription. | |
| url | string | URL to callback on when an event is published. | |
| secret | string | Secret to exchange to prove identity of event sender (not implemented yet in sample). |
Return code 404 if id is not a valid subscription.
| PUT | {IIB root}/{hookpath}/{id} | Update a subscription |
Allows the subscription to be updated. Uses exactly the same data structure as POST. Note: any id field in the message payload will be ignored and the id in the path used.
Return code 204 if successfully and returns no data.
Note: could also provide a PATCH operation for partial updates (like adding a new event)
Return code 404 if id is not a valid subscription.