Webhooks einrichten

Verwenden Sie diese Funktion, um ein externes System zu benachrichtigen, wenn in KORONA Event ein Ereignis eintritt, beispielsweise wenn eine Bestellung abgewickelt wird oder ein Kunde seine Einwilligung zum Newsletter ändert. Webhooks senden signierte JSON-Ereignisse an eine von Ihnen verwaltete HTTPS-URL.

Integrationseinstellungen und Verbindungsstatus im Backoffice — Nutzen Sie den Bereich „Integrationen“, um Anmeldedaten, den Verbindungsstatus und die Einrichtung externer Systeme zu überprüfen.

Bevor Sie beginnen

Bestätigen Sie:

Sie verfügen über einen HTTPS-Endpunkt, der POST-Anfragen empfangen und umgehend antworten kann
Sie verfügen über die Backoffice-Berechtigung zur Verwaltung von Webhook-Endpunkten unter Admin > Webhooks
Sie wissen, welche Ereignistypen das empfangende System benötigt

Erstellen Sie einen Webhook-Endpunkt

Öffnen Sie im Backoffice Admin > Webhooks.
Wählen Sie auf der Seite Webhook-Endpunkte die Option Erstellen aus.
Geben Sie die Endpunkt-URL ein. Es muss sich um eine gültige HTTPS-URL handeln.
Wählen Sie die Ereignistypen aus, die diesen Webhook auslösen sollen.
Wählen Sie optional eine Verkaufsstelle aus, um die Veranstaltungen nach einer bestimmten Verkaufsstelle zu filtern. Bei der Auswahl von Buchungsveranstaltungen ist die Angabe einer Verkaufsstelle erforderlich.
Lassen Sie die Option Aktiv ausgewählt; inaktive Webhooks empfangen keine Ereignisse.
Wählen Sie Webhook erstellen aus.
Kopieren Sie den Schlüssel aus dem Dialogfeld Webhook-Schlüssel und bewahren Sie ihn sicher auf.

Verfügbare Veranstaltungstypen

Wählen Sie beim Erstellen oder Bearbeiten eines Endpunkts aus den folgenden Ereignistypen aus:

Bestellungen: Bestellung abgeschlossen
Buchungen: Buchung angelegt, Buchung aktualisiert, Buchung storniert, Kontingent aktualisiert
Kunden: Kontakt angelegt, Kontakt aktualisiert, Kontakt gelöscht, Einwilligung zum Newsletter des Kontakts geändert, Abonnement für den Kontakt hinzugefügt, Abonnement für den Kontakt entfernt
Segmente: Segment angelegt, Segment aktualisiert, Segment gelöscht, Segmentzugehörigkeit hinzugefügt

Buchungsidentität für gruppierte Veranstaltungsvorlagen

Bei `offerable.booking.created`, `offerable.booking.updated` und `offerable.booking.cancelled` bezeichnen die `offerable_*`-Felder das öffentliche Angebot, das ein externes System abfragen oder buchen kann. Wurde ein Vorkommen anhand einer internen untergeordneten Veranstaltungsvorlage innerhalb einer Gruppe angelegt, bezeichnen diese Felder daher die öffentliche übergeordnete Veranstaltungsvorlage und nicht die interne untergeordnete Vorlage.

Feld	Buchung von Veranstaltungsvorlagen in Gruppen
`offerable_id`	ID der öffentlichen übergeordneten Veranstaltungsvorlage
`offerable_name`	Name der öffentlichen übergeordneten Veranstaltungsvorlage
`offerable_type`	`EVENT_TEMPLATE`
`on_demand_event_id`	ID des materialisierten Vorkommens
`offerable_span`, `offerable_span_begin`, `offerable_span_end`	Zeitraum, in dem dieses Ereignis stattfand

KORONA Event berechnet weiterhin die Quote und die Weiterleitung an die Verkaufsstelle anhand der internen Quellvorlage und des jeweiligen Vorfalls. Es behält die untergeordnete ID als `source_event_template_id` in den Metadaten des Integrationsereignisses für die Weiterleitung und Diagnose bei; diese internen Metadaten stellen kein zusätzliches Feld im übermittelten JSON-Body dar. Nicht gruppierte Ereignisvorlagen verwenden in beiden Rollen ihre eigene ID.

Lieferungen überprüfen

Jede Übermittlung erfolgt als JSON-POST-Anfrage, die die Ereignis-ID, den Ereignistyp und die betroffene Ressource enthält. Im Abschnitt „Webhook-Vertrag“ auf der Webhooks-Seite werden ein Beispiel für die Nutzdaten sowie die Header angezeigt:

`X-Toucantix-Webhook-Signature` – HMAC-SHA256 über `timestamp.payload` unter Verwendung des Endpunkt-Geheimnisses, formatiert als `t=<timestamp>,v1=<hex>`
`X-Webhook-Event-Id` – die stabile Ereignis-ID, die für die Deduplizierung verwendet werden soll
`X-Webhook-Event-Type` – der Ereignisschlüssel für diese Zustellung
`X-Webhook-Timestamp` – der bei der Signaturprüfung verwendete Unix-Zeitstempel

Überprüfen Sie bei jeder Zustellung die Signatur im Rohtext des Anfragetextkörpers. Vergleichen Sie den erwarteten und den empfangenen HMAC mittels eines Vergleichs in konstanter Zeit und lehnen Sie Zeitstempel ab, die mehr als fünf Minuten von der aktuellen Zeit Ihres Empfängers abweichen. Speichern Sie das `X-Webhook-Event-Id` zusammen mit dem Verarbeitungsergebnis und gestalten Sie die Verarbeitung idempotent: Eine wiederholte Ereignis-ID muss abgelehnt oder bestätigt werden, ohne dass das Ereignis zweimal verarbeitet wird. Dies schützt sowohl vor wiederholten Anfragen als auch vor normalen Zustellungswiederholungen.

Um die Verkabelung zu testen, öffnen Sie die Bearbeitungsseite des Endpunkts und wählen Sie Testereignis senden aus; KORONA Event stellt ein Beispielereignis an Ihre URL in die Warteschlange.

Übermittlung, Wiederholungsversuche und Überwachung

Fehlgeschlagene Zustellungen werden mit Zeitabständen von 30 Sekunden, 60 Sekunden, 5 Minuten, 15 Minuten und anschließend 30 Minuten erneut versucht. Sind alle Wiederholungsversuche ausgeschöpft, wird die Zustellung als „Dead Letter“ gekennzeichnet und nicht erneut versucht.

Die Liste der Webhook-Endpunkte zeigt für jeden Endpunkt die letzte Zustellung, Fehler sowie den Status „In Ordnung“, „Fehlerhaft“ oder „Deaktiviert“ an, sodass Sie einen defekten Empfänger schnell erkennen können.

Um die Zustellungen dauerhaft zu beenden, archivieren Sie den Endpunkt; durch die Archivierung werden alle Zustellungen an diese URL eingestellt, und der Vorgang kann über die Archivliste rückgängig gemacht werden.

Erwartetes Ergebnis

Ihr Endpunkt empfängt signierte JSON-Ereignisse für die ausgewählten Ereignistypen kurz nach deren Auftreten; ein Testereignis wird auf Abruf gesendet, und der Endpunkt wird in der Liste als Funktionsfähig angezeigt.

Fehlerbehebung

Problem	Was Sie überprüfen sollten
Es liegen keine Veranstaltungen vor	Der Endpunkt ist aktiv und nicht archiviert, die richtigen Ereignistypen sind ausgewählt, und es gibt keinen Verkaufsstellen-Filter, der die Ereignisse ausschließt.
Der Endpunkt zeigt Fehler an	Ihr Empfänger gibt umgehend einen Erfolgscode zurück; überprüfen Sie die Einträge unter Letzte Zustellung und Fehler in der Liste sowie in Ihren Serverprotokollen.
Die Signaturprüfung schlägt fehl	Sie überprüfen HMAC-SHA256 für `timestamp.payload` anhand des gespeicherten Geheimnisses; sollte das Geheimnis verloren gehen, erstellen Sie einen neuen Endpunkt.
Ereignisse werden nach wiederholten Fehlern beendet	Zustellungen mit Fehlermeldung werden nicht erneut versucht; beheben Sie das Problem beim Empfänger und verwenden Sie Testereignis senden, um die Wiederherstellung zu bestätigen.