Webhooks

Booked supports webhook notifications for reservation created, updated, deleted, and approved events.

Enabling Webhooks #

Webhooks require minimal configuration within Booked. Under the “gear” icon in the main navigation is an option for Integrations.

Manage the Webhook integration and toggle it to an Enabled state.

Add your Callback URL. This is the URL that will receive the POST requests for every webhook event. This should be an HTTPS endpoint. Sending webhook events via unencrypted HTTP is insecure.

Once enabled, a Signing Secret will be created. This secret will be used to sign every webhook event. Details on event validation can be found below. Strong security practices suggest that the Signing Secret be updated on a regular basis.

Implementing a Callback URL #

The configured Callback URL will be invoked for every webhook event. Booked will send an HTTP POST request to this URL with the event details.

The Callback URL implementation must accept and immediately return an HTTP success status code (200). No synchronous processing should happen in the webhook client implementation.

Validating a Webhook Event #

All event messages will be signed by the server using the configured Signing Secret. The signature will be sent in an HTTP header named X-Booked-WebHook-Signature.

Booked webhook signatures are generated using the following steps:

• JSON encode the client Callback URL, the event type property of the message, the timestamp property of the message, and the url property of the message
• Hashing the string representation of the JSON encoded data using HMAC-SHA256, using the signing key as the hash key
• Base64 encoding the final result

Example (PHP) #

$data = new stdClass();

$data->clientUrl = 'https://www.bookedscheduler.com/webhook-endpoint'; // the Callback URL configured in Booked
$data->eventType = $message->eventType;
$data->timestamp = $message->timestamp;
$data->url = $message->url;

$signature = base64_encode(hash_hmac('sha256', json_encode($data), $this->signingKey, false));

The webhook client should validate the event timestamp to ensure the message originated within an expected time threshold. This prevents replay attacks as well as ensures the message is current.

Webhook Event Structure #

All reservation events are JSON formatted and have the same message structure

{
    "eventData": {
        "accessories": [
            {
                "id": 1,
                "name": "accessory name",
                "quantity": 5
            }
        ],
        "attributes": [
            {
                "id": 1,
                "value": "value"
            }
        ],
        "coOwnerIds": [
            500,
            600
        ],
        "dateCreated": 1788382314,
        "dateModified": 1788465359,
        "description": "",
        "displayColor": "#FFFFFF",
        "endDateTimestamp": 1788456600,
        "inviteeGuests": [
            "no-reply@bookedscheduler.com"
        ],
        "inviteeIds": [
            1000,
            2000
        ],
        "ownerEmail": "support@bookedscheduler.com",
        "ownerId": 1,
        "ownerName": "Booked Scheduler",
        "participantGuests": [
            "no-reply@twinkletoessoftware.com"
        ],
        "participantIds": [
            10000,
            11111
        ],
        "recurrence": {
            "dayOfMonth": null,
            "endDateTimestamp": 1788494400,
            "type": "daily",
            "weekdays": null,
            "weekOfMonth": null
        },
        "referenceNumber": "ABC123",
        "resources": [
            {
                "id": 5,
                "name": "number 2"
            }
        ],
        "startDateTimestamp": 1788454800,
        "title": ""
    },
    "eventType": "reservation-updated",
    "timestamp": 1788465370,
    "url": "https://demo.bookedscheduler.com/Web/Services/Reservation/ABC123"
}

Details #

• All datetime values are sent as a timestamp. The timestamp does not include milliseconds.
• The eventType will be one of the following values: reservation-created, reservation-updated, reservation-approved, reservation-deleted.
• The url will point to the Booked web service endpoint to pull full reservation details.
• The recurrence type will be one of the following values: daily, weekly, monthly, yearly, custom