Een webhook voor een boekingsgebeurtenis toevoegen
Inhoudsopgave
Het toevoegen van een webhook voor boekingsgebeurtenissen stuurt boekingsgegevens in JSON-formaat naar een URL wanneer een boeking wordt aangemaakt, gewijzigd, geannuleerd of hersteld.
Belangrijke details
- Technische kennis vereist: Het instellen en beheren van webhooks vereist technische expertise. Raadpleeg indien nodig een webontwikkelaar.
- Activering: Activeer de webhook voor boekingsgebeurtenissen bij Instellingen -> Sirvoy-account -> Webhook voor boekingsgebeurtenis.
- Webhook limiet: Er kan slechts één webhook actief zijn per Sirvoy-account.
- Callback triggers: Een boekingsgebeurtenis webhook stuurt een callback naar een gespecificeerde URL telkens wanneer een boeking wordt aangemaakt, gewijzigd, geannuleerd of hersteld.
Technische benodigdheden:
- Response code: De ontvangende server moet reageren met een `200 OK` statuscode. Als dit niet het geval is, wordt de oproep tien keer opnieuw geprobeerd met een exponentiële back-off tot 10 keer voordat deze wordt verwijderd.
- HTTPS en TLS: We ondersteunen alleen HTTPS met TLS versie 1.2 of hoger om de privacy en vertrouwelijkheid van gegevens te waarborgen. Zorg ervoor dat je HTTPS-certificaat geldig is, anders worden er geen gegevens verzonden.
- Health check: Je server moet reageren op HTTP GET verzoeken met `200 OK` voor “health checks”. Er worden geen gegevens verzonden met HTTP GET, maar het zorgt ervoor dat je endpoint actief is.
Beheer boekingsmeldingen en mislukte Webhooks
We sturen een melding voor elke boekingsupdate en events kunnen in een andere volgorde worden geleverd. Gebruik de “generatedAt” tijdstempel om een nauwkeurige tijdlijn van gebeurtenissen te maken. Elke melding bevat de volledige JSON-weergave van de boeking op dat moment.
Als je endpoint begint te falen en geen succesvolle statuscodes meer terugstuurt op onze oproepen, zullen we je via e-mail op de hoogte stellen. Als het een week lang blijft mislukken, wordt de webhook verwijderd na een laatste melding.
IP-whitelisting
Om succesvolle webhook callbacks te garanderen, moet je de volgende IP-bereiken toestaan in je firewall:
- 34.243.166.60
- 52.18.11.99
- 63.34.80.48
- 54.194.0.85
- 2a05:d018:e34:5300::/56
De servers die de callbacks uitvoeren, zijn dual-stack met zowel IPv4- als IPv6-connectiviteit. Als je zowel IPv4- als IPv6-adressen aan je domeinnaam toevoegt, worden callbacks gemaakt naar de server die als eerste reageert.
Voorbeelden voor JSON-formaten
Voorbeeld JSON-structuur voor nieuwe boekingen:
{
"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 JSON-structuur voor het maken van een kassabon en het toepassen van een betaling op een factuur:
{
"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
}
]
}
]
}
Voor vragen of verdere assistentie, neem contact op met ons ondersteuningsteam.