Webhooks

This document explains what webhooks are and how they work.

Webhooks are a mechanism for Bookinglayer to notify other web applications of changes performed in the system. In other words, when certain actions get performed within the Bookinglayer system, usually when some entities get created, modified or deleted, it can automatically send an HTTP POST request to any URL that users designated with a pre-defined payload.

Payload

All payload sent via webhooks is transmitted in JSON format. The payload each webhook transmits can be divided into two categories:

1. The name of the event that triggered the webhook call

2. The custom payload that depends on the event that triggered the webhook call

1. Event name

All webhooks will contain the name of the event that triggered the call within their payload. This value will be contained under the event key in the root of the JSON payload.

2. Custom payload

Each webhook call will contain custom data that depends on the event that triggered the webhook call.

In order to keep webhook calls as lightweight as possible, Bookinglayer adopts a general consensus that custom payloads always contain the minimal data-set required for webhook clients to be able to know what happened, and based on that they can use the Bookinglayer API to obtain additional information. In other words, most webhook payloads will only contain the ID of the entity that has been affected by the event that triggered the webhook call and then clients can send a request to the API with the ID they received to fetch all details of that entity.

The custom payload will always be contained within the data object located in the root of the JSON payload.

Here is an example of the payload a webhook call triggered by the PersonCreated event would contain:

{
    "event": "PersonCreated",
    "data": {
        "id": "df499e88-9572-4a5b-a6c3-9b295129cc9b"
    }
}

All webhook events and their payloads are explained in greater detail on their dedicated resource pages.

Authenticity

All webhook calls initiated by Bookinglayer are signed in order to enforce authenticity and integrity. Bookinglayer adds a signature, created using a shared secret, to all requests which webhook clients can use to verify that their webhook URL's are actually called by Bookinglayer, and not another party. The secret also ensures the payload sent to the webhook URL's is not tampered with.

The pre-shared secret is a string used for generating webhook call signatures and that secret is not transmitted via the calls. Instead, it is visible on the webhook management page in the Backoffice and should be copied from there to webhook clients manually.

The signature is sent via the Signature header and it is a SHA-256 hash of the JSON paylod you have received, generated using the secret as the key. In order to verify the authenticity and integrity of the webhook call clients should generate a SHA-256 key using the secret that was copied from the Backoffice and confirm the generated hash matches the received signature.

PHP

public function handleWebhook(Request $request)
{
    $signature = $request->header('Signature');
    
    $secret = 'secret-copied-from-backoffice';
    
    $hash = hash_hmac('sha256', $request->getContent(), $secret);
    
    if ($hash === $signature) {
        // Authenticity and integrity are verified
    }
}

Configuring webhooks

Webhooks can be configured by authenticated users in the Backoffice. The Settings > API > Webhooks page contains a list of all the already configured webhooks and allows users to create new ones.

In order to enable webhooks users are required to configure three webhook properties:

1. URL - the URL that should be called when events occur

2. Description - arbitrary description (optional)

3. Events - list of events that should trigger webhook calls

A single webhook can have any number of events. This means that webhook clients are not required to have a separate URL for every event they need to handle, instead they can receive different events using a single URL and distinguish them using the event payload value.

In addition to the three user-configured parameters, each webhook also contains a secret. This secret is automatically generated and used for the signing process, explained previously in this document. It is visible at any time after the initial webhook configuration is completed.

Webhook logs

The webhooks configuration page in the Backoffice also contains logs of the calls made by each webhook. These logs contain every request ever sent for each webhook, and each log entry contains the following values:

• The event that triggered the call

• Date and time the call was triggered at

• The payload that was sent

• The received HTTP status code

• The received HTTP body