Webhooks

Setup

Setup the hook on the actor using xbusctl:

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:

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