Webhooks: Ereignisse, Felder und Signatur
Webhooks in Xentra einrichten: alle Ereignisse, die Feldgruppen, HMAC-Signatur, Test, Logs, Nachsenden, automatische Deaktivierung und Bot-Übergaben nach Slack.
Aktualisiert am 12. November 2026
Mit einem Webhook ruft Xentra deine URL auf, sobald etwas passiert, ganz ohne Abfragen. Einrichten: API / MCP öffnen, Reiter Webhooks, „Hinzufügen“. Name und URL eintragen, Ereignisse und Felder wählen, Erstellen.
Der Editor „Neuer Webhook“ mit der Auswahl der Ereignisse
Ereignisse
| Ereignis im Editor | Technischer Name | Wann |
|---|---|---|
| Door-Link erstellt / aktualisiert | door_link_created / door_link_updated |
Zugangslink erzeugt oder geändert |
| Check-in-Link erstellt / geändert | checkin_link_created / checkin_link_updated |
Check-in-Link erzeugt oder geändert; bei einer Mehrzimmer-Reservierung nur einmal, für das Hauptzimmer |
| Buchung erstellt | booking_created |
neue Buchung angekommen (in Echtzeit; Massenimporte und Blockierungen lösen es nicht aus) |
| Buchung aktualisiert | booking_updated |
wichtige Daten einer Buchung haben sich geändert |
| Buchung storniert | booking_cancelled |
Buchung storniert |
| Check-in abgeschlossen | checkin_completed |
Gast hat den Online-Check-in abgeschlossen |
| Rechnung erstellt | invoice_created |
Gästerechnung final erstellt (Entwürfe nicht) |
| Neue Gästenachricht | message_received |
ein Gast hat dir geschrieben, auf jedem Kanal; nur neue Nachrichten |
| Bot hat übergeben oder das Team informiert (Bereich Bot) | bot_handover |
siehe unten |
Für die Gästemappe gibt es kein Ereignis; den Link holst du bei Bedarf über die API ab.
Felder
Pro Webhook wählst du unter Payload-Felder, was mitgeschickt wird, sortiert in Gruppen:
- Standardfelder: Buchungsnummer, Buchungsnummer der Plattform, Door-Link, Check-in-Link, Gastname, Anreise, Abreise, Apartment, E-Mail, Telefon, „Gebucht am (vom Gast)“ (
booked_at) und „In Xentra angelegt am“ (created_at) - Check-in-Daten: Erwachsene, Kinder, Kleinkinder, Sprache, alle Gäste mit Dokumenten, Ankunfts- und Abreisezeit, eigene Check-in-Felder, Einwilligungen
- Komplette Gästedaten: alles aus dem Check-in in einem Feld, mit Ergebnis der Identitätsprüfung (falls aktiv)
- Rechnungsdaten: Gastadresse, abweichende Rechnungsadresse aus dem Check-in, Firma, Steuer-ID
- Buchungsfinanzen: Gesamtbetrag, Währung, Zahlungsstatus, Zahlungsmethode, Buchungsquelle, Kurtaxe
- Rechnung (nur bei „Rechnung erstellt“): Käuferdaten und Positionen der ausgestellten Rechnung
- Nachrichten: Nachrichtentext des Gastes, Übersetzung, Absender, Anhänge
Was ein Gast geschrieben hat, geht nur mit, wenn du „Nachrichtentext des Gastes“ auswählst.
Legt ein Programm einen Webhook über die API an oder ändert ihn, braucht sein Schlüssel die Rechte für die gewählten Felder und Ereignisse: Buchungsfelder Buchungen und Kalender: Lesen, Gastname, Kontakt- und Gästedaten „Gastdaten in Buchungen“, Door- und Check-in-Link Zugang, Nachrichtenfelder und „Neue Gästenachricht“ „Nachrichten an Gäste: Lesen“, Rechnungsfelder und „Rechnung erstellt“ „Rechnungen lesen“. Fehlt ein Recht, antwortet die API mit 403 und nennt die Felder. Webhooks, die du selbst in der App anlegst, betrifft das nicht. Eine fertige Voreinstellung für Lexoffice gibt es nicht; du wählst die Felder selbst.
Signatur prüfen
Beim Erstellen erzeugt Xentra einen geheimen Schlüssel und zeigt ihn genau einmal an. Jede Zustellung trägt den Header X-Webhook-Signature: sha256=<hex>, eine HMAC-SHA256 des rohen Bodys mit diesem Schlüssel. Prüf sie, bevor du reagierst. Fertige Code-Beispiele für Node, PHP und Python stehen auf der Seite API / MCP unter „Webhook-Signaturen prüfen“. Hast du den Schlüssel verloren, erzeugst du mit „Schlüssel neu generieren“ einen neuen; der alte gilt dann sofort nicht mehr.
In der Liste: testen, Protokoll, nachsenden
Ein Webhook in der Liste mit seinen Aktionen
- Test (Papierflieger) schickt eine Probe-Zustellung mit genau deinen Feldern an deine URL. So siehst du die Struktur in deinem Zielsystem, statt zu raten.
- Logs (Uhr) zeigt die letzten 30 Zustellungen mit Status und HTTP-Antwort; eine einzelne schickst du dort mit „Erneut senden“ noch einmal.
- Alle Daten synchronisieren (Play) schickt einmalig alle bestehenden Buchungen und Links an deine URL, praktisch beim Start einer neuen Anbindung.
- Mit dem Schalter Aktiv pausierst du einen Webhook.
Antwortet deine URL nicht oder mit einem Fehler, wiederholt Xentra die Zustellung mehrmals mit wachsendem Abstand. Nach 20 fehlgeschlagenen Zustellungen in Folge stoppt Xentra den Webhook und zeigt einen Hinweis; prüf dann URL und Empfänger und klick „Reaktivieren“.
Bot-Übergaben als Webhook, auch nach Slack
Das Ereignis „Bot hat übergeben oder das Team informiert“ kommt im selben Moment wie die Meldung in der Glocke: wenn der Bot eine Unterhaltung an dich abgibt, und wenn er selbst geantwortet und dem Gast zugesagt hat, dass das Team Bescheid bekommt. Trägst du als URL die Webhook-Adresse von Slack ein (hooks.slack.com), schickt Xentra eine lesbare Nachricht in deiner Sprache statt JSON. Name und Nachricht des Gastes stehen nur drin, wenn du „Gastname“ und „Nachrichtentext des Gastes“ auswählst. In den Bot-Einstellungen unter Autonomie führt ein Link direkt zu den Webhooks.
Tipp: Webhook für Echtzeit plus ein gelegentlicher Abgleich über die API ist die robusteste Kombination, siehe Daten-API: Limits, 403-Sperre und richtig synchronisieren.