Adding a booking event webhook sends booking details in JSON format to a URL whenever a booking is created, modified, canceled, or restored.
Key details
- Technical knowledge required: Setting up and managing webhooks requires technical expertise. Consult a web developer if needed.
- Activation: Activate the booking event webhook at Settings -> Sirvoy account -> Booking event webhook.
- Webhook limit: Only one webhook can be active per Sirvoy account.
- Callback triggers: A booking event webhook sends a callback to a specified URL every time a booking is created, modified, canceled, or restored.
Technical Requirements:
- Response code: The receiving server must respond with a `200 OK` status code. If not, the call will be retried ten times with exponential back-off up to 10 times before it is discarded
- HTTPS and TLS: We only support HTTPS using TLS version 1.2 or higher to ensure data privacy and confidentiality. Ensure your HTTPS certificate is valid; otherwise, no data will be sent.
- Health check: Your server must respond to HTTP GET requests with `200 OK` for health checks. No data will be sent using HTTP GET, but it ensures your endpoint is active.
Managing Booking Notifications and Webhook Failures
We send a notification for each booking update and events can be delivered out of order. Use the “generatedAt” timestamp to build an accurate timeline of events. Each notification will contain the full JSON representation of the booking at that point in time.
If your endpoint starts to fail and doesn’t return successful status codes on our calls we will notify you via email. If it continues to fail for one week, the webhook will be removed, after a final notification.
Deprecations
Version 2.0 will be released on June 10th, 2024, and is backward compatible. However, the following fields will be removed after September 1st, 2024. Please discontinue using them:
- “callbackId”
- “generatedTime”
- “bookingIsProvisional”
- “bookingProvisionalId”
IP Whitelisting
To ensure successful webhook callbacks, permit the following IP ranges in your firewall:
- 34.243.166.60
- 52.18.11.99
- 63.34.80.48
- 54.194.0.85
- 2a05:d018:e34:5300::/56
The servers making the callbacks are dual-stack, supporting both IPv4 and IPv6. If you add both IPv4 and IPv6 addresses to your domain name, the callback will be made to the first server to respond.
JSON Format Examples
Example JSON structure for new bookings:
{
"version": "2.0",
"generatedAt": "2024-05-31T12:11:53.639+00:00",
"event": "new",
"propertyId": 1,
"bookingId": 26006,
"channelBookingId": null,
"bookingDate": "2024-05-31T12:09:16+00:00",
"arrivalDate": "2024-06-01",
"departureDate": "2024-06-04",
"cancelled": false,
"eta": "10:00",
"totalAdults": 4,
"guest": {
"firstName": "John",
"lastName": "Doe",
"businessName": "Acme",
"address": "Fancy street",
"postcode": "11-111",
"city": "York",
"state": "NY",
"country": "US",
"phone": "+16033336666",
"email": "guest@email.com",
"passportNo": "XX11122223333",
"language": "en",
"message": "Additional comment added by guest"
},
"guestReference": "2103001",
"internalComment": null,
"couponCode": null,
"bookingSource": "Front desk",
"bookingIsCheckedIn": false,
"bookingIsCheckedOut": false,
"bookingIsConfirmed": true,
"customFields": [
{
"name": "Custom text field name",
"value": "text added by guest"
},
{
"name": "Custom checkbox unchecked",
"value": false
},
{
"name": "Custom checkbox checked",
"value": true
}
],
"rooms": [
{
"RoomTypeName": "Basic room",
"RoomTypeDescription": "Basic room",
"RoomName": "101",
"RoomId": 2,
"arrivalDate": "2024-06-01",
"departureDate": "2024-06-04",
"adults": 2,
"quantity": 3,
"price": 100,
"roomTotal": 300,
"guestName": null,
"comment": null,
"ledgerAccount": null
},
{
"RoomTypeName": "Fancy room",
"RoomTypeDescription": "Fancy room",
"RoomName": "182",
"RoomId": 83,
"arrivalDate": "2024-06-01",
"departureDate": "2024-06-04",
"adults": 2,
"quantity": 3,
"price": 100,
"roomTotal": 300,
"guestName": null,
"comment": null,
"ledgerAccount": null
}
],
"additionalItems": [
{
"description": "Breakfast",
"specificDate": null,
"quantity": 12,
"price": 20,
"itemTotal": 240,
"ledgerAccount": null
}
],
"bookedCategory": null,
"currency": "EUR",
"totalPrice": 840,
"totalSurcharges": 84,
"totalPriceIncludingSurcharges": 924,
"payments": [],
"invoices": [],
"--DEPRECATED--": "The fields callbackId, generatedTime, bookingIsProvisional, bookingProvisionalId WILL BE REMOVED after 2024-09-01",
"callbackId": 1,
"generatedTime": "2024-05-31T12:11:53+00:00",
"bookingIsProvisional": false,
"bookingProvisionalId": null
}
Example JSON structure for creating a cash receipt and applying a payment to an invoice:
{
"version": "2.0",
"generatedAt": "2024-05-31T12:15:23.895+00:00",
"event": "modified",
"propertyId": 1,
"bookingId": 26006,
"channelBookingId": null,
"bookingDate": "2024-05-31T12:09:16+00:00",
"arrivalDate": "2024-06-01",
"departureDate": "2024-06-04",
"cancelled": false,
"eta": "10:00",
"totalAdults": 4,
"guest": {
"firstName": "John",
"lastName": "Doe",
"businessName": "Acme",
"address": "Fancy street",
"postcode": "11-111",
"city": "York",
"state": "NY",
"country": "US",
"phone": "+16033336666",
"email": "guest@email.com",
"passportNo": "XX11122223333",
"language": "en",
"message": "Additional comment added by guest"
},
"guestReference": "2103001",
"internalComment": null,
"couponCode": null,
"bookingSource": "Front desk",
"bookingIsCheckedIn": false,
"bookingIsCheckedOut": false,
"bookingIsConfirmed": true,
"customFields": [
{
"name": "Custom text field name",
"value": "text added by guest"
},
{
"name": "Custom checkbox unchecked",
"value": false
},
{
"name": "Custom checkbox checked",
"value": true
}
],
"rooms": [
{
"RoomTypeName": "Basic room",
"RoomTypeDescription": "Basic room",
"RoomName": "101",
"RoomId": 2,
"arrivalDate": "2024-06-01",
"departureDate": "2024-06-04",
"adults": 2,
"quantity": 3,
"price": 100,
"roomTotal": 300,
"guestName": null,
"comment": null,
"ledgerAccount": null
},
{
"RoomTypeName": "Fancy room",
"RoomTypeDescription": "Fancy room",
"RoomName": "182",
"RoomId": 83,
"arrivalDate": "2024-06-01",
"departureDate": "2024-06-04",
"adults": 2,
"quantity": 3,
"price": 100,
"roomTotal": 300,
"guestName": null,
"comment": null,
"ledgerAccount": null
}
],
"additionalItems": [
{
"description": "Breakfast",
"specificDate": null,
"quantity": 12,
"price": 20,
"itemTotal": 240,
"ledgerAccount": null
}
],
"bookedCategory": null,
"currency": "EUR",
"totalPrice": 840,
"totalSurcharges": 84,
"totalPriceIncludingSurcharges": 924,
"payments": [],
"invoices": [
{
"invoiceNumber": "41002",
"invoiceDate": "2024-06-01",
"dueDate": "2024-06-01",
"receiver": "Acme",
"address": [
"John Doe",
"Fancy street",
"York, NY 11-111",
"United States"
],
"roundingAmount": 0,
"invoiceTotal": 924,
"originInvoice": null,
"invoiceRows": [
{
"quantity": 3,
"price": 100,
"rowTotal": 300,
"ledgerAccount": "100",
"rowText": "Basic room",
"vatRate": 0,
"vatAmount": 0,
"bookingId": 26006
},
{
"quantity": 3,
"price": 100,
"rowTotal": 300,
"ledgerAccount": "100",
"rowText": "Fancy room",
"vatRate": 0,
"vatAmount": 0,
"bookingId": 26006
},
{
"quantity": 12,
"price": 20,
"rowTotal": 240,
"ledgerAccount": "200",
"rowText": "Breakfast",
"vatRate": 0,
"vatAmount": 0,
"bookingId": 26006
},
{
"quantity": 1,
"price": 84,
"rowTotal": 84,
"ledgerAccount": "300",
"rowText": "surcharge",
"vatRate": 0,
"vatAmount": 0,
"bookingId": 26006
}
],
"payments": [
{
"paymentId": 28,
"createdAt": "2024-05-31T12:15:09+00:00",
"valueDate": "2024-06-01",
"amount": 924,
"ledgerAccount": "3606",
"paymentReference": null,
"comment": null
}
]
}
],
"--DEPRECATED--": "The fields callbackId, generatedTime, bookingIsProvisional, bookingProvisionalId WILL BE REMOVED after 2024-09-01",
"callbackId": 1,
"generatedTime": "2024-05-31T12:15:23+00:00",
"bookingIsProvisional": false,
"bookingProvisionalId": null
}
For any questions or further assistance, contact our support team.