Webhooks einrichten

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

Bevor Sie beginnen

Bestätigen Sie:

• Sie verfügen über einen HTTPS-Endpunkt, der POST-Anfragen empfangen und schnell antworten kann
• Sie verfügen über die Backoffice-Berechtigung, Webhook-Endpunkte unter Admin > Webhooks zu verwalten
• Sie wissen, welche Ereignistypen das empfangende System benötigt

Erstellen Sie einen Webhook-Endpunkt

1. Öffnen Sie im Backoffice Admin > Webhooks.
2. Wählen Sie auf der Seite Webhook-Endpunkte die Option Erstellen aus.
3. Geben Sie die Endpunkt-URL ein. Es muss sich um eine gültige HTTPS-URL handeln.
4. Wählen Sie die Veranstaltungstypen aus, die diesen Webhook auslösen sollen.
5. Wählen Sie optional einen Verkaufspunkt aus, um die Ereignisse auf einen Verkaufspunkt zu beschränken. Bei Buchungsereignissen ist ein Verkaufspunkt erforderlich.
6. Lassen Sie die Option Aktiv ausgewählt; inaktive Webhooks empfangen keine Ereignisse.
7. Wählen Sie Webhook erstellen aus.
8. Kopieren Sie das Geheimnis aus dem Dialogfeld Webhook-Geheimnis und bewahren Sie es sicher auf.

Verfügbare Ereignistypen

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

• Bestellungen: Bestellung abgerechnet
• Buchungen: Buchung erstellt, Buchung aktualisiert, Buchung storniert, Aktualisierte Quoten
• Kunden: Kontakt erstellt, Kontakt aktualisiert, Kontakt gelöscht, Newsletter-Einwilligung geändert, Kontakt-Abonnement hinzugefügt, Kontakt-Abonnement entfernt
• Segmente: Segment erstellt, Segment aktualisiert, Segment gelöscht, Segment-Mitgliedschaft hinzugefügt

„Bestellung abgerechnet“ für externe Analytics verwenden

Bestellung abgerechnet ist eine serverseitige Benachrichtigung darüber, dass eine Bestellung den Status „abgerechnet“ erreicht hat. Die Daten enthalten Bestellnummer, Zahlungsstatus und Zahlungsart, Währung, Gesamtbetrag, abgerechneten Bruttowert, abgerechnete Positionen, Gutscheine und die folgenden additiven Fiskalfelder:

Jeder Geldwert im Webhook ist ein Objekt mit dem Dezimal-String amount, den ganzzahligen cents und der ISO-Währung currency. Verwenden Sie für einen exakten Abgleich die cents der Positionssummen. Ein Stückwert wird bei einer Division mit Rest auf die kleinste Währungseinheit gerundet. Hat eine abgerechnete Position die Menge null, werden beide Stückwertfelder weggelassen, weil kein Stückwert berechnet werden kann. Steuersätze sind numerische Prozentwerte; 19 bedeutet also 19 %.

Bei Kassenbonpositionen mit verifizierter gespeicherter Nettosumme sind die gespeicherten Brutto- und Nettosummen des Kassenbons maßgeblich; tax ist deren Differenz. Steuerkomponenten mit Steuersatz werden nur ausgegeben, wenn die Summe ihrer rekonstruierten Werte genau diesem maßgeblichen Steuerbetrag entspricht. Andernfalls enthält die Aufschlüsselung eine Komponente mit dem maßgeblichen tax_value; tax_rate und included sind dabei null. Empfänger dürfen daraus keine Zuordnung zu einem Steuersatz ableiten.

Historische Kassenbonpositionen, die vor der Speicherung von Nettosummen erstellt wurden, werden nicht als Käufe mit Nettowert null behandelt. Ihre additiven Fiskalfelder auf Positionsebene werden weggelassen; dies gilt auch für davon abhängige Netto- und Steuer-Gesamtsummen der Bestellung. Fiskalfelder werden ebenfalls weggelassen, wenn die gespeicherten Währungen einer Kassenbonposition nicht mit der Bestellwährung übereinstimmen. Empfänger dürfen cents-Werte unterschiedlicher Währungen nicht addieren.

Kassenbonpositionen speichern keinen maßgeblichen Rabatt auf Positionsebene. KORONA Event lässt discount deshalb bei Kassenbonpositionen weg, statt einen Rabatt der Preiszeile für mehrere Kassenbonpositionen zu wiederholen. Rechnungspositionen enthalten weiterhin ihren gespeicherten Positionsrabatt.

Die Versandklassifizierung wird mit jeder abgerechneten Position gespeichert. Eine spätere Änderung des konfigurierten Versandartikels klassifiziert diese gespeicherte Zuordnung nicht neu. Ein neu konfigurierter Artikel gilt erst bei Positionen als Versand, die nach der Änderung erstellt werden. Positionen, die bereits vor Einführung des Snapshot-Felds bestanden, wurden anhand des beim Upgrade konfigurierten Versandartikels klassifiziert. Ihre Zuordnung entspricht daher möglicherweise nicht einer früheren Konfiguration.

Die Netto- und Steuerwerte auf Bestellungsebene summieren abgerechnete Positionen. Gutscheine, Kontotransaktionen und andere Anpassungen auf Bestellungsebene werden nicht auf diese Werte verteilt. Verwenden Sie zum Abgleich der gesamten Bestellung weiterhin data.order.total_gross und settled_gross. Die Vertragsversion des Webhooks bleibt 1, weil die bestehenden Felder und Bedeutungen unverändert bleiben und die Fiskalfelder additiv sind. Empfänger müssen unbekannte Felder ignorieren und damit umgehen, dass die neuen Felder in älteren oder schrittweise eingeführten Übermittlungen fehlen können.

Es handelt sich nicht um einen vorgefertigten Google Ads- oder GA4-Conversion-Feed. Der Webhook enthält keine Browser-Kampagnenparameter oder Klick-Identifikatoren wie gclid, fbclid oder UTM-Werte. Eine serverseitige Werbeintegration muss die gesetzlich zulässige Klick- oder Sitzungskennung separat beziehen, sie mit der abgerechneten Bestellung verknüpfen, die dokumentierten Fiskalfelder für ihre Zielplattform transformieren, Webhook-Übermittlungen deduplizieren und die Zielanfrage selbst versenden.

Für browserbasierte Kampagnenzuordnung und Kaufereignisse verwenden Sie Externe Analytics und Consent einrichten.

Buchungskennung für gruppierte Veranstaltungsvorlagen

Bei offerable.booking.created, offerable.booking.updated und offerable.booking.cancelled kennzeichnen 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.

KORONA Event berechnet weiterhin die Kontingentierung und die Weiterleitung an die Verkaufsstelle anhand der internen Quellvorlage und des jeweiligen Vorkommens. 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 Zustellung erfolgt als JSON-POST-Anfrage. Es gibt keine universelle Hülle: Bestell- und Segmentmitgliedschaftsereignisse verwenden kanonische Ereignisfelder wie key, version, occurred_at und tenant. Buchungs-, Kontingent- und Legacy-Datensatzänderungsvarianten verwenden dagegen type, created_at, tenant_id und tenant_slug. contact.created und contact.updated können sowohl in einer kanonischen als auch in einer Legacy-Variante zugestellt werden, wenn beide produktiven Abonnementwege aktiv sind. Richten Sie Ihren Empfänger nach dem Ereignis und der Payload-Familie in der vollständigen Webhook-Referenz aus, nicht nach einem einzelnen Beispieltextkörper. Die Referenz ist auf Englisch verfügbar.

Jede produktive Zustellung enthält diese gemeinsamen maßgeblichen Header:

• Content-Type – application/json
• X-Webhook-Signature – HMAC-SHA256 über <timestamp>.<JSON-Rohtextkörper> unter Verwendung des Endpunkt-Geheimnisses, formatiert als t=<timestamp>,v1=<hex>
• X-Webhook-Event-Id – die Datenbank-Ereignis-ID des Zustellungswegs; verwenden Sie sie für die Deduplizierung
• X-Webhook-Event-Type – der Ereignisschlüssel für diese Zustellung
• X-Webhook-Timestamp – der bei der Signaturprüfung verwendete Unix-Zeitstempel

Der Integrations- und der Legacy-Zustellungsweg ergänzen Kompatibilitätsaliasnamen und wegspezifische Metadaten-Header. Die vollständige Webhook-Referenz listet diese auf und zeigt, welchen Weg ein Ereignis derzeit verwendet. Benutzerdefinierte Header können unabhängig von ihrer Groß- und Kleinschreibung keinen maßgeblichen Header ersetzen. Sie können einen benutzerdefinierten Authorization-Header für Ihren Empfänger verwenden.

Ü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 Zustellungsversuchen.

Um die Einrichtung zu testen, öffnen Sie die Bearbeitungsseite des Endpunkts und wählen Sie Test-Event senden aus. Diese Aktion reiht das Beispiel immer über den Legacy-Zustellungsweg ein. Textkörper und wegspezifische Header können daher von der produktiven Zustellung desselben Ereignisses abweichen. Verwenden Sie den Test für die Verbindung und Signaturprüfung und prüfen Sie Ihren Parser anschließend mit der produktiven Variante aus der Referenz.

Übermittlung, Wiederholungsversuche und Überwachung

Eine Zustellung umfasst insgesamt fünf Versuche: den ersten Versuch und bei einem wiederholbaren Fehler weitere Versuche nach 30 Sekunden, 60 Sekunden, 5 Minuten und 15 Minuten. Es gibt keinen fünften Wiederholungsversuch nach 30 Minuten. Der Integrationsweg wiederholt HTTP-408-, HTTP-425-, HTTP-429- und HTTP-5xx-Antworten; der Legacy-Weg wiederholt HTTP-408-, HTTP-429-, HTTP-499- und HTTP-5xx-Antworten. Beide Wege wiederholen Verbindungs- und Zeitüberschreitungsfehler. Sind alle Versuche ausgeschöpft, wird die Zustellung als „Dead Letter“ gekennzeichnet und nicht erneut versucht.

KORONA Event lässt 5 Sekunden für den Verbindungsaufbau und 10 Sekunden für den Empfang der Antwort zu. Überprüfen Sie die Signatur, reihen Sie die dauerhafte Verarbeitung ein und geben Sie innerhalb dieser Antwort-/Lesezeit von 10 Sekunden eine 2xx-Antwort zurück. Führen Sie vor der Bestätigung der Zustellung keine lang laufenden Arbeiten aus. Eine Zeitüberschreitung beim Verbindungsaufbau oder bei der Antwort gilt als fehlgeschlagener Versuch und kann eine Wiederholung auslösen.

Die Liste der Webhook-Endpunkte zeigt für jeden Endpunkt die Letzte Zustellung, Fehler und den Status Verfügbar, Fehlerhaft oder Deaktiviert an, sodass Sie einen defekten Empfänger schnell erkennen können.

Um neue Zustellungen zu unterbinden, archivieren Sie den Endpunkt. Dadurch wird er aus den aktiven Abonnements entfernt; Sie können den Vorgang über die Liste der archivierten Einträge rückgängig machen. Eine bereits eingereihte oder laufende Anfrage kann Ihre URL trotzdem noch erreichen. Lassen Sie deshalb die Signaturprüfung und die idempotente Verarbeitung während des Übergangs aktiv.

Erwartetes Ergebnis

Ihr Endpunkt empfängt signierte JSON-Ereignisse für die ausgewählten Ereignistypen kurz nach deren Eintreten. Ein Testereignis wird auf Anfrage gesendet und der Endpunkt wird in der Liste als Verfügbar angezeigt.

Fehlerbehebung

Verwandte Artikel

• API-Zugriff erhalten
• Vollständige Webhook-Referenz (Englisch)
• Checkliste zur Fehlerbehebung bei der Integration