Webhooks voor boekingsgebeurtenissen gebruiken

Hoe boekingsgegevens naar een extern systeem kunnen worden verzonden wanneer boekingen worden aangemaakt, gewijzigd, geannuleerd of hersteld.

+ More

Inhoudsopgave

Een nieuwe webhook voor boekingsgebeurtenissen aanmaken Hoe callbacks werken en welke vereisten gelden Voorkom dat je firewall callbacks blokkeert Voorbeelden van JSON-callbacks Voorbeeld: Callback voor een nieuwe boeking Voorbeeld: Callback voor een nieuwe boeking met financiële gegevens

Webhooks zorgen ervoor dat Sirvoy automatisch kan communiceren met andere systemen. Zo kan bijvoorbeeld een sleutelloos toegangssysteem automatisch een deurcode aanmaken of kan boekingsinformatie rechtstreeks naar je boekhoudsoftware worden gestuurd.

Met een webhook verstuurt Sirvoy boekingsgegevens in JSON-formaat (een standaardformaat waarmee applicaties gegevens uitwisselen) naar een door jou opgegeven webadres (URL). Elke keer dat Sirvoy gegevens naar deze URL verstuurt, wordt dit een callback genoemd.

Andere programma’s kunnen de naar de URL verzonden gegevens ontvangen en deze gebruiken voor geautomatiseerde taken.

Opmerking: Webhooks zijn alleen beschikbaar in Sirvoy Pro. Je kunt maximaal tien webhooks per account toevoegen. Het instellen en beheren van webhooks vereist technische kennis. Als je hier niet mee vertrouwd bent, raden we aan een webontwikkelaar te raadplegen.

Een nieuwe webhook voor boekingsgebeurtenissen aanmaken

Ga naar Instellingen > Sirvoy-account
Klik onder Webhook voor boekingsgebeurtenis op Toevoegen
Voer de Callback-URL in
Geef de webhook een naam
Klik op Opslaan

Sirvoy stuurt vanaf nu automatisch een callback naar deze URL wanneer een boeking wordt aangemaakt, gewijzigd, geannuleerd of hersteld.

Hoe callbacks werken en welke vereisten gelden

Responsafhandeling: De server die de callback ontvangt, moet antwoorden met de statuscode 200 OK. Dit betekent dat de gegevens succesvol zijn ontvangen en verwerkt. Ontvangt Sirvoy geen 200 OK-respons, dan wordt de callback maximaal tien keer opnieuw verzonden. Tussen elke poging wordt de wachttijd steeds langer. Als de callback ook daarna blijft mislukken, ontvang je een e-mailmelding. Na een laatste waarschuwing wordt de webhook automatisch verwijderd.
HTTPS en TLS: De webhook-URL moet beveiligd zijn (beginnen met https://) en gebruikmaken van de TLS-versie 1.2 of hoger. TLS (Transport Layer Security) versleutelt gegevens tijdens verzending, zodat onbevoegden deze niet kunnen onderscheppen of lezen. Als het HTTPS-certificaat van je server ongeldig is, zal Sirvoy geen gegevens verzenden.
Gezondheidscontroles (Health checks): Sirvoy controleert regelmatig of je URL nog bereikbaar is door een eenvoudige HTTP GET-aanvraag te sturen. Hierbij worden geen boekingsgegevens meegestuurd; het is enkel een controle of de server beschikbaar is. Je server moet hierop antwoorden met 200 OK om aan te geven dat alles correct werkt.
Volgorde van gebeurtenissen: Voor elke boekingsgebeurtenis wordt een webhook verstuurd. Het is echter mogelijk dat gebeurtenissen niet in de juiste volgorde aankomen. Bijvoorbeeld: een wijziging van een boeking kan worden ontvangen voordat de oorspronkelijke boeking zelf wordt ontvangen. Gebruik daarom altijd de tijdstempel generatedAt in elk bericht om gebeurtenissen in de juiste volgorde te verwerken.

Voorkom dat je firewall callbacks blokkeert

Als je systeem gebruikmaakt van een firewall (software of hardware die ongewenst internetverkeer blokkeert), moet je mogelijk bepaalde IP-adressen whitelisten. Whitelisten betekent dat verkeer van specifieke bronnen wordt toegestaan terwijl ander verkeer wordt geblokkeerd.

Whitelist de volgende IP-adressen:

34.243.166.60
52.18.11.99
63.34.80.48
54.194.0.85
2a05:d018:e34:5300::/56

Callbacks worden verzonden vanaf servers die zowel IPv4 (de oudere internetstandaard) als IPv6 (de nieuwere standaard) ondersteunen.

Voorbeelden van JSON-callbacks

De onderstaande voorbeelden laten zien welke gegevens Sirvoy naar je webhook-URL verzendt en hoe deze gegevens zijn opgebouwd.

Deze voorbeelden zijn vooral nuttig voor ontwikkelaars of voor iedereen die een systeem bouwt dat boekingsgegevens uit Sirvoy moet ontvangen en verwerken.

Het eerste voorbeeld toont een standaard callback voor een nieuwe boeking. De tweede bevat meer details, zoals facturen en betalingen, om te laten zien wat er precies bij hoort als het om financiële gegevens gaat.

Voorbeeld: Callback voor een nieuwe boeking

"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": []
}

Voorbeeld: Callback voor een nieuwe boeking met financiële gegevens

{
	"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
            	}
        	]
    	}
	]
}

systemen voor toegang op afstand software-integratie automatisering van hotelboekingen webhook voor boekingsgebeurtenissen webhooks automatisering van boekingsfacturen geautomatiseerde boekingsupdates callback voor boekingsgebeurtenissen ontwikkeltools voor hotelsoftware beveiligde webhook via tls json-boekingsgegevens automatisering van horecasoftware