> ## Documentation Index > Fetch the complete documentation index at: https://docs.selfbook.com/llms.txt > Use this file to discover all available pages before exploring further. # Webhooks Overview 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. * **PAYMENT\_AUTHORISATION**: Sent when successful authorisations are made against the guest's credit card. This is not a standard webhook and requires a specific configuraton on the partner's API account. * **PAYMENT\_CAPTURE**: Sent when successful captures are made against a previous authorization. This is not a standard webhook and requires a specific configuraton on the partner's API account. ## 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. | Property | Description | | --------------- | ------------------------------------------------------------------------------------- | | event\_id | Unique identifier for the event. | | event\_time | Timestamp of the event. ISO 8601 format. | | event\_type | Type of event. See Supported events. | | reservation\_id | Id of the related reservation. | | retry\_count | If delivery has failed in the past, this value would be incremented for each attempt. | | signature | HMAC signature used to verify webhook | | version | 1 | 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](https://en.wikipedia.org/wiki/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. Note: This calculation should be based on a byte array size of 32. 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":["guest_payment_token"],"retry_count":0,"signature":"c0HpuTW+R3YyPzbFgSoEpwDOhk6GpoicTTJ1V5sOm1w="}]} ``` ### PAYMENT\_AUTHORISATION Triggered upon Selfbook receiving a successful authorisation on a guest's payment method. ``` {"events":[{"event_id":"S69YBZTNW8E1::16988CAF12DBDB436971","event_type":"PAYMENT_AUTHORISATION","reservation_id":"S69YBZTNW8E1ZSKFNHFZICG2TOVB8LKL","version":1,"event_time":"2025-07-31T12:15:10.972Z","retry_count":0,"signature":"3jgszHXYl+Dt/oMhdgBFSUfuo73ASOnq8HK9NDF01zc=","amount":100,"currency_code":"USD","network_trace_id":"008169727923027","reservation_booking_code":"A0HD0Y","retrieval_reference_number":"LL33GJJK6JK"}]} ``` ### PAYMENT\_CAPTURE Triggered upon Selfbook receiving a successful capture on a guest's payment method. ``` {"events":[{"event_id":"S69YBZTNW8E1::A596E7A5FB5EA2CB7380","event_type":"PAYMENT_CAPTURE","reservation_id":"S69YBZTNW8E1ZSKFNHFZICG2TOVB8LKL","version":1,"event_time":"2025-08-01T21:04:03.108Z","retry_count":0,"signature":"Dn8rNmPv5GSOHK2Qn/IHvRw23tKAh7QyBZIKNZIATK0=","acquirer_reference_number":"arn1754514121546","amount":100,"currency_code":"USD"}]} ```