Use booking event webhooks
How to send booking data to an external system when bookings are created, modified, canceled, or restored.
Table of Contents
Webhooks let Sirvoy talk to other tools automatically—like telling a keyless entry system when to create a room code or sending invoicing details to your accounting software.
With a webhook, Sirvoy sends booking details in JSON format (a standard way for apps to share data) to a web address (URL) that you choose. A callback is whenever data is sent to that URL.
Other programs can receive the details sent to the URL and use the data for automated tasks.
Note: Webhooks are available only in Sirvoy Pro. You can add up to ten webhooks per account. Setting up and managing webhooks requires technical knowledge, so consider consulting a web developer.
Create a new booking event webhook
- Go to Settings > Sirvoy account
- Under Booking event webhook, click Add
- Enter the Callback URL
- Give the webhook a name
- Click Save
Sirvoy will now send a callback to that URL whenever a booking is created, modified, canceled, or restored.
How callbacks work and what’s required
-
Response handling: The server receiving the callback needs to reply with a
200 OKstatus code, which means “everything worked”. If it doesn’t, Sirvoy will retry sending the callback up to 10 times, spacing out each attempt more and more, before stopping altogether. If callbacks continue to fail, we’ll notify you by email and remove the webhook after a final notice. -
HTTPS and TLS: Your webhook URL must be secure (start with
https://) and use TLS version 1.2 or higher. TLS (Transport Layer Security) encrypts the data so no one can read it while it’s being sent. If your HTTPS certificate isn’t valid, Sirvoy won’t send any data. -
Health checks: Sirvoy occasionally checks if your URL is active by sending a simple
HTTP GETrequest (a way to ask your server “are you there?” without sending data). Your server must respond with200 OK(“everything worked”) for these checks to succeed. -
Event order: A webhook is sent for every booking event, but events may arrive out of order—for example, a modification might arrive before the original booking event. Use the
generatedAttimestamp in each message to arrange them in the correct order.
Keep your firewall from blocking callbacks
If your system uses a firewall (software or hardware that blocks unwanted internet traffic), you may need to whitelist certain IP addresses. Whitelisting means allowing traffic from specific sources while blocking others.
Whitelist these IP addresses:
34.243.166.60
52.18.11.99
63.34.80.48
54.194.0.85
2a05:d018:e34:5300::/56Callbacks are sent from servers that support both IPv4 (the older internet addressing standard) and IPv6 (the newer one).
Example JSON callbacks
These examples show the kind of data Sirvoy sends to your webhook URL and how it’s formatted.
They’re useful for developers or anyone building a system that needs to receive and process booking data from Sirvoy.
The first example shows a basic callback for a new booking. The second includes more detail, such as invoices and payments, to show what’s included when financial data is involved.
Example: New booking callback
"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": []
}Example: New booking callback with financial data
{
"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
}
]
}
]
}