Webhooks let an application be notified of events occurring in Bookeo. For example Bookeo can notify the application when a new booking is created, or a booking is canceled.
When an application needs to be updated with events in Bookeo (ex. to take specific actions triggered by events, or to sync changed data), it is strongly recommended to use webhooks instead of polling the API for changed data.
An application can manage webhooks for each API key it has access to. Bookeo supports different webhook “domains”, i.e. the type of data that the webhook is notified for, and webhook “types”, i.e. types of event for which the application is notified.
For example, a webhook domain is “bookings”, and a webhook type is “created”. A webhook registered for API key ABC, for domain “bookings” and type “created” will be notified whenever a new booking is created for the account linked to the API Key “ABC”.
A full list of possible values for domain and type of a webhook is provided in the API reference for the POST /webhooks method: http://www.bookeo.com/apiref/index.html#!/Webhooks/webhooks_post
Each webhook has a URL, which is the address where the notifications for that webhook will be sent to.
An application can register a different webhook for each combination of API key, domain and type. No more than one webhook can be registered for the same combination of API Key, domain and type. To create a webhook, simply submit an HTTP POST to the API endpoint /webhooks (see API reference for full details).
The webhook URL can contain custom parameters. You can use this to provide context information to your web service about the webhook call. For example you could use this URL:
https://www.mydomain.com/webhooks/newbooking?account=1234
or this URL:
https://www.mydomain.com/1234/webhooks?type=bookingCreated
… and so on. You can use any URL you want, as long as the protocol is https.
When the associated event occurs, Bookeo will send an HTTP POST request to the URL of the webhook registered for that event. Bookeo will assume that the message has been received successfully by the application only when it receives a 2xx HTTP response status code. Any other code will be interpreted as an error, and delivery will be attempted again later (see below).
The request entity body will contain a JSON object with this format:
WebhookMessage {
itemId (string),
item (object),
timestamp (date-time),
}itemId is the unique identifier of the item that the notification is for. For bookings, this would be the bookingNumber. For customers and for payments, this would be the id.
itemId can be used to take some action without having to decode the full item (see below)
item is the json representation of the item (ex. the booking) that the notification is for. See the API references for the full structure of these objects (the same as returned by GET /bookings/{itemId}, GET /customers/{itemId}, GET /payments/{itemId}, etc.)
timestamp is the time at which the notification was generated. Note that this may be considerably earlier than the time at which the message is eventually delivered.
{
"itemId": "85504203869114",
"timestamp": "2015-04-21T17:02:00+10:00",
"item": {
"bookingNumber": "85504203869114",
"startTime": "2015-04-22T17:00:00+10:00",
...
}
}
When delivered to the webhook registered for the domain “bookings” and the type “created”, this is a message to notify of the creation of a new booking 85504203869114.
If delivery of a webhook message fails for any reason (network error, HTTP response status code other than 200, etc.), Bookeo will retry delivery several times, at exponentially longer intervals between each attempt.
Note that webhooks are delivered in strict sequence for each API Key, meaning that if event A and B for an API Key occur in this order, Bookeo will not send notification for B until the notification for A is delivered successfully, or completely discarded (see below).
If Bookeo is unable to deliver a webhook message after multiple attempts, it will discard the message, and the message will be forever lost.
If more messages for the same webhook are due to be sent after the discarded one, Bookeo will try and deliver them as usual.
The first message successfully sent after a discarded message will include the HTTP request header X-Bookeo-PreviousMessageLost with a value of true. This header, when present, indicates that the message before the current one was discarded. Note that possibly other messages before that could have been discarded as well.
Bookeo will attempt delivery for at least 6 hours before discarding a message.
If Bookeo is unable to deliver any message to a webhook URL for prolonged periods of times (more than 24 hours), the webhook will be considered unresponsive, and it will be blocked. No more message deliveries will be attempted for this webhook.
An application that has not been receiving notifications for a while can periodically check the status of its webhooks (see API reference) to see if any of its webhooks was blocked. In this case, an application should fix the cause of the problem, and can then register a new webhook to replace the existing one.
Bookeo expects the webhook message to be processed quickly (within 5 seconds).
If your application needs to perform complex tasks as a result of receiving a webhook message, we strongly recommend queuing the message internally, returning the HTTP response to Bookeo quickly, and then processing the message in the background.
Please note that webhooks are a resource-consuming feature. Bookeo reserves the right to block an application whose webhook URLs are often unreliable, not accessible, unresponsive, slow, etc.