.. _http-webhooks:

Webhooks
========

Setup
-----

Setup the hook on the actor using xbusctl:

.. code-block:: bash

    xbusctl actor config set <actor name> http.webhook.url=http<...>

Additionnaly, the following settings can be customized:

- ``http.webhook.content-type``:  'application/json' (default) or 'application/x-protobuf')
- ``http.webhook.http-codes.success``: A comma-separated list of http status
  codes that should be interpreted as success.  Default is "200".
- ``http.webhook.http-codes.temporary-failure``: A comma-separated list of http
  status codes that should be interpreted as temporary failure, which imply
  xbus reattempting until it gets a success or an error.  Default is an empty list.


For example:

.. code-block:: bash

    xbusctl actor config set my-frontend-consumer http.webhook.url=https://myfrontend.com/webhook/somehardtoguesswebpath
    xbusctl actor config set my-frontend-consumer http.webhook.content-type=application/x-protobuf
    xbusctl actor config set my-frontend-consumer http.webhook.http-codes.temporary-failure=502,503

.. warning::

    The xbus-http instance must be restarted after setting up a webhook.

API
---

The gateway will POST new requests on the url.

The response must be a properly encoded ActorProcessingState. If not, the
process will fail.

If the status of the returned state is 'RUNNING', the client must call
'/processingend' later.

**Example request**:

.. sourcecode:: http

    POST /my/hook/webpath HTTP/1.1
    Host: example.com
    Accept: application/json
    Accept-Item-Encoding: binary
    Content-Type: application/json

    {
        "context": {},
        "inputs": [{
            "name": "default",
            "envelope": {
                "event_ids": ["53131466-4e2e-11e7-916e-af2b1e6d242d"],
                "events": [{
                    "id": "53131466-4e2e-11e7-916e-af2b1e6d242d",
                    "type": "test",
                    "ItemCount": 1,
                    "encoding": "binary",
                    "items": ["QSBtZXNzYWdl"]
                }]
            },
            "envelopeposition": {
                "envelope_id": "53131466-4e2e-11e7-916e-af2b1e6d242d",
                "start": true,
                "complete": true,
                "eventPosisions": [{
                    "event_id": "53131466-4e2e-11e7-916e-af2b1e6d242d",
                    "index": 1,
                    "itemCount": 1
                }]
            }
        }]
    }


**Example response**

.. sourcecode:: http

    {
        "context": {},
        "status": "SUCCESS",
        "messages": [{
            "timestamp": "2018-08-20T22:56:12Z",
            "level": "NOTICE",
            "text": "Hello there"
        }]
    }