Webhooks

Setup

Setup the hook on the actor using xbusctl:

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

Added in version 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:
```
xbusctl actor config set <actor name> http.webhook.headers="
Authorization: Bearer AJSONWEBTOKEN
Accept-Language: fr-FR
"
```

Added in version 3.3.0:

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

For example:

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:

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

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