Webhooks

The concept of a WebHook is simple. A WebHook is an HTTP callback: an HTTP POST that occurs when something happens; a simple event-notification via HTTP POST. A web application implementing WebHooks will POST a message to a URL when certain things happen. When a web application enables users to register their own URLs, the users can then extend, customize, and integrate that application with their own custom extensions or even with other applications around the web. For the user, WebHooks are a way to receive valuable information when it happens, rather than continually polling for that data and receiving nothing valuable most of the time

It should be possible to programmatically register webhooks via the api

It SHOULD be possible to programmatically add, update and list webhooks by issueing POST, PUT and GET request against a resource collection containing webhooks. The name of this collection SHOULD be hooks.

Example :

POST /v1/hooks HTTP/1.1
Host: api.provider.com
Content-Type: application/json

{
  "url": "http://api.consumer.com/callback/url",
  "events": [
    "transactionStatusChanged"
  ],
  "secret": "very_s3cr3t",
  "active": true
}

Webhooks may be registered on all resource types

Webhooks MAY be registered on individual resources such as advertisement entities, resource collections, such as a list of advertisements or on the on the api root resource. This will ensure that consumers have fine grained control over what updates they are interested in

The body of a callback must be a HAL resource

The body of a callback must be a HAL resource and follow the rules defined resource representation format section of this document Example :

POST /callback/url HTTP/1.1
Host: api.consumer.com
Content-Type: application/json
X-Ecg-Signature: b613679a0814d9ec772f95d778c35fc5ff1697c493715653c6c712144292c5ad

{
  "_links":{
    "curies":[
      {
         "href": "/v1/docs/rels/{rel}.html",
         "templated": true,
         "name": "ec"
      }
    ]
  },
  "_embedded": {
      "ec:transaction": {
          "_links": {
              "self": { "href": " /v1/advertisements/m123456789/transactions/123" }
          },
          "transactionId": 2

          .. rest of the fields go here
      }
  },
  "eventType": "transactionStatusChanged",
  "created": "2014-07-03T15:14:06Z",
  "eventData": {
      "transactionId": 2,
      "oldStatus": "unpaid",
      "newStatus": "paid"
  }
}

HTTP callbacks should be signed

HTTP callbacks SHOULD be signed so that the consumer can validate the message’s authenticity. The signature MUST be sent as a request header with the name X-Ecg-Signature The signature MUST be a HMAC-SHA-256 hex digest of the payload, using the hook’s secret as the key. This secret has been provided as part of the hook’s registration.

Events pushed to the consumers may additionally be exposed in a collection resource

The events that are posted to the the registered consumer MAY also be exposed as a resource collection in the API. The name of this collection resource SHOULD be events, and this collection MUST be exposed on the same level as the hooks resource. When events are exposed in such a fashion then the events resources posted to the callback url MUST contain a self link.