.. index:: Webhooks

.. _web-hooks:


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 :

.. code-block:: http

    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 :

.. code-block:: http

    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.