Webhooks & Events
Ein Webhook-Abonnement sagt LIKE MAGIC: „Immer wenn eines dieser Dinge passiert, sende einen HTTP-Aufruf an diese URL.“ Es ist die operative Art, ein externes System an den Event & Data Hub der Plattform anzubinden, damit dieses System automatisch reagieren kann, sobald ein Event eintritt: eine Nachricht auslösen, eine Partnerplattform aktualisieren oder einen Workflow starten.
Dies ist eine Anleitung für den Account Administrator, der Abonnements einrichtet. Sie setzt voraus, dass du bereits einen Endpunkt hast (eine URL auf deiner Seite oder der deines Integrationspartners), der HTTP-Anfragen empfangen kann.
1. Wer kann das nutzen
Webhook-Abonnements werden auf Kontoebene verwaltet (sie können eine oder mehrere Properties im Konto ansprechen). Um sie zu nutzen:
- benötigt dein Konto das Platform Pricing. Auf Core wird die Seite der Webhook-Abonnements gesperrt und mit Upgrade-Hinweis angezeigt, siehe Pricing-Tiers,
- und du benötigst die Rolle Account Administrator (
account-admin), um ein Abonnement zu erstellen oder zu ändern. Account Viewer (account-viewer) kann den Bildschirm nur lesend öffnen.
Da ein Abonnement operative Daten an ein externes System sendet, behandle das Einrichten als sicherheitsrelevante Aktion.
2. Was ein Abonnement enthält
Jedes Abonnement hat:
- einen Namen: eine lesbare Bezeichnung, damit du Abonnements unterscheiden kannst,
- eine Callback-URL: den Endpunkt, den LIKE MAGIC aufruft, wenn ein abonniertes Event auslöst,
- ein Secret: den geteilten Wert, der mit jeder Zustellung mitgesendet wird, damit dein Endpunkt erkennen kann, dass der Aufruf wirklich von LIKE MAGIC stammt,
- ein oder mehrere Topics: die Events, die du empfangen möchtest,
- eine oder mehrere Properties: für welche Properties dieses Abonnement Events abdeckt,
- einen Status: ob das Abonnement gerade aktiviert ist und zustellt.
3. Ein Abonnement erstellen
Wähle unter Einstellungen → Konto → Webhook die Aktion New Subscription und fülle aus:
- Webhook-Name: z. B. „Partner-CRM (Reservierungen)".
- Callback-URL: der Endpunkt, der die Events empfängt. Sie muss mit
https://beginnen. - Secret: füge dein eigenes ein oder nutze Zufälliges Geheimnis generieren, um eines zu erzeugen; du kannst es beim Bearbeiten ein- oder ausblenden. Kopiere es in dein empfangendes System, damit es jede Zustellung prüfen kann (siehe Abschnitt 5).
- Auf folgende Objekte anwenden: wähle die Properties, deren Events zugestellt werden sollen. Lass das Feld leer, um alle Properties abzudecken, auch später hinzugefügte.
- Topics: hake die Events an, die du erhalten möchtest (Abschnitt 4).
Ein neues Abonnement startet aktiviert und stellt zu, sobald du speicherst. Verifiziere den Endpunkt, bevor du dich darauf verlässt.
4. Auswählen, welche Events du erhältst
Du abonnierst bestimmte Topics statt „alles". Topics sind nach Bereich gruppiert, abonniere nur, was deine Integration wirklich braucht:
| Bereich | Beispiel-Topics |
|---|---|
| Buchung (IBE) | Buchung erfolgreich / fehlgeschlagen, Buchung erstellt / aktualisiert |
| Reservierung | erstellt, aktualisiert, ein-/ausgecheckt, storniert, No-Show, Zimmer-Upgrade, Pre-Check-in-/Pre-Check-out-Änderungen |
| Folio & Abrechnung | Folio erstellt, Folio aktualisiert |
| Türen & Schlösser | Türöffnung erfolgreich / fehlgeschlagen, Türzugangs-Sync, Schloss-/Gateway-Verbindung verloren / wiederhergestellt |
| Einheiten & Profile | Einheit erstellt / aktualisiert, Profil erstellt / aktualisiert / zusammengeführt, Profilsprache aktualisiert |
| Aufgaben | Aufgabe erstellt, aktualisiert, abgeschlossen |
| Messaging | Konversation erstellt / aktualisiert / gelöst, Nachricht gesendet / empfangen / fehlgeschlagen |
| Benachrichtigungen | Reservierungs-, Buchungs- und Kontobenachrichtigung gesendet / fehlgeschlagen |
| Konfiguration & Promo | Mandantenkonfiguration aktualisiert, Promo-Code erstellt / aktualisiert / gelöscht / verwendet |
💡 Abonniere gezielt. Jedes zusätzliche Topic bedeutet mehr Traffic zu deinem Endpunkt und mehr, worüber du nachdenken musst. Beginne mit den Events, auf die deine Integration reagiert, und ergänze später weitere.
Für das Gesamtbild des Event-Rückgrats hinter diesen Topics siehe den Konzeptartikel Event & Data Hub.
5. Zustellungen mit einem Secret signieren
Das Secret ist die Art, wie dein Endpunkt weiss, dass eine Zustellung wirklich von LIKE MAGIC stammt und nicht gefälscht ist. LIKE MAGIC stellt jedes Event als HTTPS-POST zu und legt das Secret in den Header lm-webhook-secret. Dein empfangendes System vergleicht diesen Header mit dem konfigurierten Secret und weist den Aufruf ab, wenn er nicht übereinstimmt.
Behandle das Secret wie ein Passwort:
- speichere es im Secret-Store deiner Integration, niemals in einem geteilten Dokument oder im Quellcode,
- wenn du vermutest, dass es geleakt ist, bearbeite das Abonnement und generiere ein neues,
- akzeptiere an deinem Endpunkt niemals einen Aufruf, der das erwartete Secret nicht mitbringt.
6. Den Endpunkt verifizieren
Bevor du einem Abonnement vertraust, nutze die Aktion Überprüfen. Sie erscheint, wenn du ein gespeichertes Abonnement öffnest, sendet einen Testaufruf an deine Callback-URL und meldet zurück, ob dein Endpunkt ihn akzeptiert hat. Schlägt die Überprüfung fehl, zeigt die Fehlermeldung, was dein Endpunkt geantwortet hat, damit du debuggen kannst. Häufig ist die URL falsch, der Endpunkt nicht erreichbar oder er hat den Aufruf abgelehnt, weil das Secret nicht übereinstimmt.
Behebe die Ursache und überprüfe erneut, bis es gelingt.
7. Welche Events eine Property ausgibt
Reservierungs-, Folio- und Buchungs-Events stammen aus dem angebundenen PMS der Property, daher hängt es von diesem PMS ab, welche Events eine Property ausgibt und wann.
Events, die intern zu LIKE MAGIC gehören (Aufgaben, Messaging, Türen, Konfiguration, Promo-Codes), sind nicht in gleicher Weise an das PMS gebunden. Wenn ein reservierungsbezogenes Topic für eine Property nie auszulösen scheint, prüfe, ob ihr PMS dieses Event tatsächlich ausgibt.
8. Bearbeiten, pausieren und löschen
- Bearbeiten, um ein Abonnement umzubenennen, seine Topics oder Properties zu ändern oder das Secret zu rotieren.
- Deaktivieren, um die Zustellung zu pausieren, ohne die Konfiguration zu verlieren, nützlich, während du einen defekten Endpunkt reparierst. Aktivieren setzt sie fort, und die Spalte Status zeigt, in welchem Zustand ein Abonnement ist.
- Löschen, um das Abonnement vollständig zu entfernen und jede Zustellung an diesen Endpunkt zu stoppen.
ℹ️ Hinweis: Das Entfernen eines Topics oder das Pausieren eines Abonnements wirkt für neue Events; vergangene Events werden nicht erneut gesendet. Plane bei Bedarf ein Nachladen über die API, wenn dein System Historie benötigt, die es während der Pause verpasst hat.
Damit das empfangende System Events oder Metriken auch direkt aus der API lesen kann, gib ihm ein eingeschränktes Service-Konto (die Scopes webhook_subscription.read, event_log.read und metric.read sind hier relevant).
9. Fazit
Ein Webhook-Abonnement ist die Self-Service-Art, ein externes System an den Live-Event-Strom von LIKE MAGIC anzubinden: benenne es, richte es auf deinen Endpunkt, gib ihm ein Secret, abonniere nur die Topics, die du brauchst, und überprüfe es, bevor du dich darauf verlässt. Für das Gesamtbild der verfügbaren Events siehe den Event & Data Hub.