Selfbook provides webhooks for certain events related to our API operations. You can choose to subscribe to one or more of these events based on your integration needs.

​
Supported events

  • RESERVATION_CANCELED: Sent when a reservation is canceled through our cancelation endpoint.

  • RESERVATION_COMPLETED: Sent when a reservation is completed. This is sent on the date of checkout.

  • RESERVATION_CONFIRMED: Sent when a reservation is confirmed with a hotel confirmation number.

  • RESERVATION_MODIFIED: Sent when a reservation is modified through our modification endpoint.

​
Set up webhooks.

Contact us to get going. We will work with you setup delivery of webhooks to your endpoints. This includes providing you with a signing secret for verification.

​
Webhook Structure

Selfbook webhooks are JSON formatted messages sent via HTTP POST to a server you control. Each webhook will have the following fields. Please note that as more event types are added, these instructions are subject to change.

PropertyDescription
event_idUnique identifier for the event.
event_timeTimestamp of the event. ISO 8601 format.
event_typeType of event. See Supported events.
reservation_idId of the related reservation.
retry_countIf delivery has failed in the past, this value would be incremented for each attempt.
signatureHMAC signature used to verify webhook
version1

For example, a RESERVATION_CANCELED webhook might look like this

{"events":[{"event_id":"6PLOQPCRH9CQ::71A7C87FB3927840DE49","event_type":"RESERVATION_CANCELED","reservation_id":"6PLOQPCRH9CQKVIPQRUKFJYBY4OGVW7O","version":1,"event_time":"2025-02-13T15:11:45.214Z","retry_count":0,"signature":"v4G9MppD7P0b5sSsye7JETQKKdoiylijEnRLgt9CtP4="}]}

​
Security

To verify the webhooks received are from us, we include a HMAC signature in the payload.

To peform a validation, follow these steps:

  1. Concatenate the values of the following fields in this order. Separate values with a colon (:).

    • event_type
    • event_id
    • event_time
    • reservation_id
    • your api username
    • your HMAC key

  2. Calculate the SHA256 HMAC signature using the key and the concatened values as described in step 1.

  3. Base64-encode the final result.

  4. Compare the value you calculated with the signature value you received in the webhook body. If it matches, you know the webhook was sent by Selfbook.

Here’s an example function in Ruby that would calculate the signature.

  • data = the fields you concatened together with a colon (:) (see step 1 above). In the example below, it’s already done and stored in ‘data’ variable.
  • key = the HMAC key you are provided with.
def create_webhook_signature(data, key)
  OpenSSL::HMAC.base64digest('sha256', key, data)
end

​
Handling webhooks

Selfbook expects you to acknowledge receiving the webhook by returning an HTTP 200 immediately upon receipt. We suggest you store any webhooks you receive and respond immediately with HTTP 200 before doing any further processing with webhook data. Selfbook allows 2000 ms (2 seconds) for your server to respond back with HTTP 200 before considering the attempt a timeout.

Selfbook will re-try sending webhooks if the initial attempt fails for up to 2 days after the initial delivery attempt.

​
Example webhooks

​
RESERVATION_CANCELED

{"events":[{"event_id":"6PLOQPCRH9CQ::71A7C87FB3927840DE49","event_type":"RESERVATION_CANCELED","reservation_id":"6PLOQPCRH9CQKVIPQRUKFJYBY4OGVW7O","version":1,"event_time":"2025-02-13T15:11:45.214Z","retry_count":0,"signature":"v4G9MppD7P0b5sSsye7JETQKKdoiylijEnRLgt9CtP4="}]}

​
RESERVATION_COMPLETED

{"events":[{"event_id":"6PLOQPCRH9CQ::6B84869BA05E10503597","event_type":"RESERVATION_COMPLETED","reservation_id":"6PLOQPCRH9CQKVIPQRUKFJYBY4OGVW7O","version":1,"event_time":"2025-02-13T15:09:38.627Z","retry_count":0,"signature":"tdGkZeaJVJa9e1Ja3mvRzjGdXFOK2JBd6BY77VSRkZ0="}]}

​
RESERVATION_CONFIRMED

Triggered upon successful confirmation of a reservation. Includes field confirmation which will have the hotel_confirmation_number.

{"events":[{"event_id":"4E2LUGJLCN2D::B52CD0E69CC56C64205D","event_type":"RESERVATION_CONFIRMED","reservation_id":"4E2LUGJLCN2DTJPBMGLOLX5OVTPKSYBI","version":1,"confirmation":{"hotel_confirmation_number":"TEST4091","record_locator":"B7K8WJ"},"event_time":"2025-02-18T15:56:06.124Z","retry_count":0,"signature":"wWnMOj/DuW5SA5m+gMrqSrZanC6PPgBhKfp7dFuEuPM="}]}

​
RESERVATION_MODIFIED

Triggered upon successful modification of a reservation. Includes field modifications which indicates the type of modification.

modifications can be: reservation_dates or guest_payment_token.

{"events":[{"event_id":"KYK3OAYIT3I3::BEBF542DECB7A7F1F7DC","event_type":"RESERVATION_MODIFIED","reservation_id":"KYK3OAYIT3I3NZ7K9RKY9I4W3BMCRMAD","version":1,"event_time":"2025-02-13T14:31:25.992Z","modifications":["payment_token"],"retry_count":0,"signature":"c0HpuTW+R3YyPzbFgSoEpwDOhk6GpoicTTJ1V5sOm1w="}]}