Einen Webhook für ein Buchungsevent hinzufügen
Inhaltsverzeichnis
Das Hinzufügen eines Webhooks für ein Buchungsevent sendet Buchungsdetails im JSON-Format an eine URL, wenn eine Buchung erstellt, geändert, storniert oder wiederhergestellt wird.
Wichtige Details
- Technische Kenntnisse erforderlich: Die Einrichtung und Verwaltung von Webhooks erfordert technisches Know-how. Wende dich bei Bedarf an einen Webentwickler.
- Aktivierung: Aktiviere den Webhook für Buchungsevents unter Einstellungen -> Sirvoy Konto -> Buchungsevent-Webhook.
- Webhook-Limit: Pro Sirvoy-Konto kann nur ein Webhook aktiv sein.
- Callback-Auslöser: Ein Buchungsevent-Webhook sendet jedes Mal, wenn eine Buchung erstellt, geändert, storniert oder wiederhergestellt wird, einen Callback an eine bestimmte URL.
Technische Voraussetzungen:
- Antwortcode: Der empfangende Server muss mit einem Statuscode „200 OK“ antworten. Ist dies nicht der Fall, wird der Rückruf zehnmal mit exponentiellem Backoff bis zu zehnmal wiederholt, bevor er verworfen wird.
- HTTPS und TLS: Wir unterstützen nur HTTPS mit TLS Version 1.2 oder höher, um Datenschutz und Vertraulichkeit zu gewährleisten. Stelle sicher, dass dein HTTPS-Zertifikat gültig ist; andernfalls werden keine Daten gesendet.
- Gesundheits-Check: Dein Server muss auf HTTP-GET-Anfragen mit „200 OK“ antworten, wenn er Gesundheits-Checks durchführt. Mit HTTP GET werden zwar keine Daten gesendet, aber es wird sichergestellt, dass dein Endpunkt aktiv ist.
Verwaltung von Buchungsbenachrichtigungen und Webhook-Fehlern
Für jede Buchungsaktualisierung wird eine Benachrichtigung versandt, und Events können außer der Reihe zugestellt werden. Verwende den Zeitstempel „generatedAt“, um eine genaue Zeitleiste der Events zu erstellen. Jede Benachrichtigung enthält die vollständige JSON-Darstellung der Buchung zu diesem Zeitpunkt.
Wenn dein Endpunkt ausfällt und bei unseren Aufrufen keine erfolgreichen Statuscodes zurückgibt, werden wir dich per E-Mail benachrichtigen. Wenn er eine Woche lang nicht funktioniert, wird der Webhook nach einer letzten Benachrichtigung entfernt.
IP-Whitelisting
Um erfolgreiche Webhook-Callbacks zu gewährleisten, lasse die folgenden IP-Bereiche in deiner Firewall zu:
- 34.243.166.60
- 52.18.11.99
- 63.34.80.48
- 54.194.0.85
- 2a05:d018:e34:5300::/56
Die Server, die die Callbacks durchführen, sind Dual-Stack-Server mit IPv4- und IPv6-Konnektivität. Wenn du sowohl IPv4 als auch IPv6 Adressen zu deiner Domain hinzufügst, wird der Callback zu dem Server getätigt, der als Erster antwortet.
Beispiele für das JSON-Format
Beispiel einer JSON-Struktur für neue Buchungen:
{
"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": []
}
Beispiel einer JSON-Struktur zur Erstellung eines Kassenbelegs und zur Zuordnung einer Zahlung zu einer Rechnung:
{
"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
}
]
}
]
}
Für Fragen oder weitere Hilfe, kontaktiere unser Support-Team.