.. _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<...>

The ``http.webhook.url`` may contain a "{msgtype}" placeholder that will be
replace by the message type. The value will be empty for ``full-request`` and
``envelope`` payload types

.. versionadded:: 3.3.0
   - The *{msgtype}* placeholder

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" for 'request'
  payload types, and "204" for 'envelope' and 'content' payload types.

- ``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.

- ``http.webhook.payload-type``: Determines how to post the data to the target
  url. The possible values are:

  - "full-request" (default): The full request is serialized and posted. The
    reply body must be a proper ``ActorProcessingState``.

  - "envelope": post only the envelope and expects no content in return with a
    204 status.

  - "message-in-request": post individual messages in a request. The envelope
    id is not changed. As with "full-request", the reply body must be a proper
    ``ActorProcessingState``.

  - "message-in-envelope": post individual messages in an envelope. The envelope
    id will be the same as the original envelope. The reply must be empty with
    a 204 status code.

  - "message-content": post the messages raw contents, one by one, with the
    configured content-type. The reply must be empty with a 204 status code.

- ``http.webhook.headers``: Add custom headers to the request

  The value is a multi-line string, each line is a single header formatted as ``Key: Value``.
  Example:

  .. code:: http

    xbusctl actor config set <actor name> http.webhook.headers="
    Authorization: Bearer AJSONWEBTOKEN
    Accept-Language: fr-FR
    "

.. versionadded:: 3.3.0

   - The *http.webhook.payload-type* parameter.
   - The *http.webhook.headers* parameter.




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"
        }]
    }