Creating an endpoint for webhooks
Your endpoint must be an HTTPS webhook address with a valid SSL certificate that can correctly process event notifications as described below. You must also implement verification to make sure webhook requests originate from Bókun.
Payloads
Payloads contain a JSON object with the data for the webhook event. The contents and structure of each payload varies depending on the subscribed event.
Receiving a webhook
After you register a webhook URL, Bókun issues an HTTP POST request to the URL specified every time that event occurs. The request's POST parameters contain JSON data relevant to the event that triggered the request.
Make sure your server is correctly configured to support HTTPS with a valid SSL certificate.
Responding to a webhook
Your webhook acknowledges that it received data by sending a 200 OK response. Any response outside of the 200 range, including 3XX HTTP redirection codes, indicates that you did not receive the webhook. Bókun does not follow redirects for webhook notifications and considers them to be an error response.
Frequency
Bókun has implemented a five second timeout period and a retry period for subscriptions. Bókun waits five seconds for a response to each request to a webhook. If there is no response, or an error is returned, then Bókun retries the connection a few times. If the retries all fail, then the webhook subscription is automatically deleted. A warning that the subscription will be deleted is sent to the app's emergency developer email address.
To avoid timeouts and errors, consider deferring app processing until after the webhook response has been successfully sent.
Verifying webhooks
Webhooks for your App are verified by calculating a digital signature. Each webhook request includes a base64-encoded X-Bokun-HMAC header, which is generated using the app's secret key along with the data sent in the request.
To verify that the request came from Bókun, compute the HMAC digest according to the following algorithm and compare it to the value in the X-Bokun-HMAC header. If they match, then you can be sure that the webhook was sent from Bókun.
- Take all the request headers that start with
X-Bokun.
- Make sure you exclude the
X-Bokun-HMACheader from the list.
- Transform the header names to lower case, and then order them alphabetically by header name.
- Append the headers and their values into a single string using the following format:
header1=value1&header2=value2
For example, if you had the following headers:
x-bokun-apikey: bb5d27dda5a24c4eaf8263ac5a5054f8
x-bokun-experience-id: RXhwZXJpZW5jZToyNjA5
x-bokun-hmac: a59876dd257d700931076e56b061a0e8a14f29ea067eaba6a777c33afbf1e7fb
x-bokun-topic: experiences/availability_update
x-bokun-vendor-id: VmVuZG9yOjQ
Then the string would look like this:
x-bokun-apikey=bb5d27dda5a24c4eaf8263ac5a5054f8&x-bokun-experience-id=RXhwZXJpZW5jZToyNjA5&x-bokun-topic=experiences/availability_update&x-bokun-vendor-id=VmVuZG9yOjQ
- Next, you process the string through an
HMAC-SHA256hash function using the app API secret key. The request is authentic if the generated hexdigest is equal to the value of theX-Bokun-HMACheader.