Buchungs-Event-Webhooks verwenden

So sendest du Buchungsdaten an ein externes System, wenn Buchungen erstellt, geändert, storniert oder wiederhergestellt werden.

+ Mehr

Inhaltsverzeichnis

Neuen Buchungsevent-Webhook erstellen So funktionieren Callbacks und das ist erforderlich Verhindere, dass deine Firewall Callbacks blockiert Beispiele für JSON-Callbacks Beispiel: Callback für neue Buchung Beispiel: Callback für neue Buchung mit Finanzdaten

Mit Webhooks kann Sirvoy automatisch mit anderen Tools kommunizieren – zum Beispiel, um einem System für schlüssellosen Zugang mitzuteilen, wann ein Zimmercode erstellt werden soll, oder Rechnungsdetails an deine Buchhaltungssoftware zu senden.

Mit einem Webhook sendet Sirvoy Buchungsdetails im JSON-Format (eine standardisierte Methode, mit der Apps Daten austauschen) an eine von dir gewählte Webadresse (URL). Ein Callback erfolgt immer dann, wenn Daten an diese URL gesendet werden.

Andere Programme können die an die URL gesendeten Details empfangen und die Daten für automatisierte Aufgaben verwenden.

Beachte: Webhooks sind nur in Sirvoy Pro verfügbar. Du kannst bis zu zehn Webhooks pro Konto hinzufügen. Das Einrichten und Verwalten von Webhooks erfordert technisches Wissen, daher solltest du in Erwägung ziehen, einen Webentwickler hinzuzuziehen.

Neuen Buchungsevent-Webhook erstellen

Gehe zu Einstellungen > Sirvoy Konto
Klicke unter Buchungsevent-Webhook, auf Hinzufügen
Gib die Callback-URL ein
Gib dem Webhook einen Namen
Klicke auf Speichern

Sirvoy sendet nun immer dann einen Callback an diese URL, wenn eine Buchung erstellt, geändert, storniert oder wiederhergestellt wird.

So funktionieren Callbacks und das ist erforderlich

Antwortverarbeitung: Der Server, der den Callback empfängt, muss mit dem Statuscode 200 OK antworten, was bedeutet: „Alles hat funktioniert“. Wenn er das nicht tut, versucht Sirvoy bis zu 10-mal erneut, den Callback zu senden, wobei die Abstände zwischen den Versuchen immer größer werden, bevor die Versuche vollständig eingestellt werden. Wenn Callbacks weiterhin fehlschlagen, benachrichtigen wir dich per E-Mail und entfernen den Webhook nach einer letzten Benachrichtigung.
HTTPS und TLS: Ihre Webhook-URL muss sicher sein (mit https:// beginnen) und TLS-Version 1.2 oder höher verwenden. TLS (Transport Layer Security) verschlüsselt die Daten, damit niemand sie lesen kann, während sie gesendet werden. Wenn dein HTTPS-Zertifikat nicht gültig ist, sendet Sirvoy keine Daten.
Health Checks: Sirvoy prüft gelegentlich, ob deine URL aktiv ist, indem eine einfache HTTP-GET-Anfrage sendet (eine Möglichkeit, deinen Server zu fragen: „Bist du da?“, ohne Daten zu senden). Dein Server muss für diese Prüfungen mit 200 OK („Alles hat funktioniert“) antworten.
Event-Reihenfolge: Für jedes Buchungsevent wird ein Webhook gesendet, aber Events können in einer anderen Reihenfolge eintreffen – zum Beispiel kann eine Änderung vor dem ursprünglichen Buchungsevent eintreffen. Verwende den Zeitstempel generatedAt in jeder Nachricht, um sie in die richtige Reihenfolge zu bringen.

Verhindere, dass deine Firewall Callbacks blockiert

Wenn dein System eine Firewall verwendet (Software oder Hardware, die unerwünschten Internetverkehr blockiert), musst du möglicherweise bestimmte IP-Adressen auf die Whitelist setzen. Whitelisting bedeutet, Datenverkehr aus bestimmten Quellen zuzulassen und andere zu blockieren.

Setze diese IP-Adressen auf die Whitelist:

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

Callbacks werden von Servern gesendet, die sowohl IPv4 (den älteren Standard für Internetadressierung) als auch IPv6 (den neueren Standard) unterstützen.

Beispiele für JSON-Callbacks

Diese Beispiele zeigen, welche Art von Daten Sirvoy an deine Webhook-URL sendet und wie sie formatiert sind.

Sie sind nützlich für Entwickler oder alle, die ein System erstellen, das Buchungsdaten von Sirvoy empfangen und verarbeiten muss.

Das erste Beispiel zeigt einen einfachen Callback für eine neue Buchung. Das zweite enthält mehr Details, wie Rechnungen und Zahlungen, um zu zeigen, was enthalten ist, wenn Finanzdaten beteiligt sind.

Beispiel: Callback für neue Buchung

"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: Callback für neue Buchung mit Finanzdaten

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

buchungs-event-webhook webhooks json-buchungsdaten automatisierung von hospitality-software buchungsdaten-api integration mit buchhaltungssoftware schlüsselloser zimmerzugang systeme für remote-zugang softwareintegration hotelbuchungsautomatisierung sicherer webhook tls