Webhooks einrichten

Verwenden Sie diese Funktion, um ein externes System zu benachrichtigen, wenn in KORONA Event ein Ereignis eintritt, beispielsweise wenn ein Vorgang 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 Verwaltung > Webhooks zu verwalten
• Sie wissen, welche Ereignistypen das empfangende System benötigt

Erstellen Sie einen Webhook-Endpunkt

1. Öffnen Sie im Backoffice Verwaltung > 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 Ereignistypen 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:

• Vorgänge: Vorgang 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
• Scans: Validierung geprüft, Eintritt bestätigt, Austritt bestätigt, Andere Bestätigung

Scans von ausgewählten Einlasspunkten weiterleiten

Verbinden Sie KORONA.entry, bevor Sie die Scanweiterleitung einrichten. Die Einlasspunkte werden im Rahmen der regulären KORONA-Synchronisierung alle 15 Minuten importiert. Um sie früher zu importieren, öffnen Sie Integrationen und wählen Sie im Abschnitt KORONA.cloud die Option Synchronisieren aus. Dafür benötigen Sie weder eine Kunden-E-Mail-Adresse noch personalisierte Mitteilungen oder die Ausgabe von Coupons. Die Weiterleitung gilt für neu empfangene Scans; das Aktivieren spielt keine historischen Scanaktivitäten erneut ab.

1. Wählen Sie Eintritt bestätigt für Eintrittsaktivitäten, Austritt bestätigt für Austritte oder Validierung geprüft für Validierungsprüfungen. Andere Bestätigung umfasst Bestätigungen mit unbekannter Richtung.
2. Wählen Sie unter Scanfilter die Einlasspunkte. Suchen Sie nach dem Namen oder der Nummer des Einlasspunkts und wählen Sie anschließend die passenden Einlasspunkte aus KORONA.entry aus. Wählen Sie Mehr laden, um die nächste Ergebnisseite anzuzeigen. Lassen Sie die Auswahl leer, um Scans von allen Einlasspunkten zu empfangen.
3. Wählen Sie für erfolgreiche Eintritte unter Scanergebnisse die Option Eintritt akzeptiert und unter Scanrichtungen die Option Eintritt. Eine erfolgreiche Validierung allein bedeutet nicht, dass der Besucher eingetreten ist.
4. Beschränken Sie Scans bei Bedarf auf Ticketartikel oder Verknüpfte Veranstaltungen. Diese Filter benötigen einen zugeordneten lokalen Ticketanspruch beziehungsweise eine zugeordnete Teilnahme. Ein nicht zugeordnetes Ticket kann weiterhin weitergeleitet werden, wenn kein solcher Filter ausgewählt ist.
5. Lassen Sie Originaldaten des Anbieters einschließen deaktiviert, sofern der Empfänger keine zusätzlichen Ticketdetails des Anbieters benötigt. Bei aktivierter Option werden eingehende Zugangsdaten entfernt.
6. Speichern Sie den Endpunkt und bewahren Sie den Signaturschlüssel auf. Prüfen Sie mit Testereignis senden die Verbindung zum Empfänger und die Signatur. Testereignisse sind als Beispiele gekennzeichnet und umgehen die Endpunktfilter. Prüfen Sie die Einlasspunktauswahl mit einem tatsächlichen Scan am ausgewählten Einlasspunkt.

Scanfilter gelten für Scanereignisse. Die Auswahl Verkaufspunkt gilt für Ereignisse außerhalb von Scans, einschließlich Buchungen; Scans verwenden ihre eigenen Scanfilter. Alle ausgewählten Filtergruppen müssen übereinstimmen. Mehrere Werte innerhalb einer Gruppe sind Alternativen. Maßgeblich ist der Einlasspunkt, an dem der Scan tatsächlich stattfand, nicht die im Ticket erlaubten Einlasspunkte. Ein Scan ohne Einlasspunktnummer kann keine ausgewählte Nummer erfüllen. Die Auswahl gilt für das jeweilige KORONA.entry-Konto; überprüfen Sie sie bei einem Kontowechsel.

Eintritt bestätigt umfasst auch abgelehnte Versuche. Nur eine ausdrücklich erfolgreiche Zutrittsbestätigung erhält das Ergebnis Eintritt akzeptiert. Leere Ergebnisse bleiben unbekannt. Austritte gelten nicht als erfolgreiche Eintritte. Diese Benachrichtigungen beschreiben Scanaktivitäten des Anbieters; sie vergeben keine Besucherprämien und versenden keine Teilnahmemitteilungen.

Scandaten und Wiederherstellung

Der Empfänger erhält das Ergebnis, den Ablehnungsgrund, die Richtung, die Einlasspunktnummer, die Anzahl der Nutzungen bei Gruppenscans, die Scanzeit des Anbieters, die Empfangszeit und eine stabile Quellkennung. Einlasspunktnamen werden ergänzt, wenn sie im Katalog verfügbar sind; gemeldete Einlasspunktnummern bleiben auch ohne Katalognamen erhalten. Scans können verspätet oder in anderer Reihenfolge eintreffen. Verarbeiten Sie Ereignisse anhand ihrer Kennung und verwenden Sie die Zustellzeit nicht als Scanzeit.

Die JSON-Kennung id stimmt mit X-ToucanTix-Event-Id überein. Speichern Sie sie, um wiederholte Zustellungen zu erkennen. Wiederholte eingehende Scans behalten dieselbe Ereigniskennung. Die lokale Ticketzuordnung kann separat erneut versucht werden, ohne einen weiteren Scan zu veröffentlichen oder die Weiterleitung zu wiederholen.

Prüfen Sie bei fehlgeschlagener Zustellung die Zustellungsüberwachung und korrigieren Sie die Empfänger-URL, den Signaturschlüssel oder die Verfügbarkeit des Empfängers. Vorübergehende Fehler werden automatisch erneut versucht. Der Empfänger muss doppelte Zustellungen sicher verarbeiten. Verwenden Sie nach Abschluss der Synchronisierung die Funktion Einlasspunkte neu laden, um die aktualisierte Einlasspunktliste zu laden. Fehlende lokale Ticketdaten verhindern keine ungefilterte Weiterleitung, können aber ausgewählte Ticketartikel- oder Veranstaltungsfilter nicht erfüllen.

„Vorgang abgerechnet“ für externe Analytics verwenden

Vorgang abgerechnet ist eine serverseitige Benachrichtigung darüber, dass ein Vorgang den Status „abgerechnet“ erreicht hat. Die Daten enthalten Vorgangsnummer, 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 des Vorgangs. Fiskalfelder werden ebenfalls weggelassen, wenn die gespeicherten Währungen einer Kassenbonposition nicht mit der Währung des Vorgangs ü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 Vorgangsebene summieren abgerechnete Positionen. Gutscheine, Kontotransaktionen und andere Anpassungen auf Vorgangsebene werden nicht auf diese Werte verteilt. Verwenden Sie zum Abgleich des gesamten Vorgangs 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 dem abgerechneten Vorgang 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 Eventvorlagen

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 Eventvorlage innerhalb einer Gruppe angelegt, bezeichnen diese Felder daher die öffentliche übergeordnete Eventvorlage und nicht die interne untergeordnete Vorlage.

KORONA Event leitet Buchungsbenachrichtigungen anhand der internen Quellvorlage und des jeweiligen Termins weiter. Bei Eventbuchungen für einen Endpunkt mit genau einem ausgewählten POS entspricht die übermittelte Kapazität dem öffentlichen Angebot für diesen POS. Die untergeordnete ID bleibt als source_event_template_id in den Metadaten des Integrationsereignisses für Weiterleitung und Diagnose erhalten; diese internen Metadaten sind kein zusätzliches Feld im zugestellten JSON-Body. Nicht gruppierte Eventvorlagen verwenden in beiden Rollen ihre eigene ID.

Kapazität in Buchungsbenachrichtigungen

Wählen Sie für Buchungen von Events und Eventvorlagen genau einen Verkaufspunkt für den Endpunkt aus. data.current_attributes.remaining_quota ist die absolute Anzahl der Plätze, die dieser POS aktuell verkaufen kann. KORONA Event berechnet sie vor jedem Zustellversuch einschließlich Wiederholungen neu. Dabei werden das POS-Kontingent des öffentlichen Termins, die Gesamtkapazität, die Ressourcenverfügbarkeit, der Veröffentlichungsstatus und das Verkaufsfenster berücksichtigt. Ausverkaufte, überbuchte, entfernte und geschlossene Angebote melden null. current_attributes.pos_id identifiziert den empfangenden POS; observed_at gibt den Zeitpunkt der Kapazitätsabfrage an.

Ersetzen Sie die externe Verfügbarkeit durch diesen absoluten Wert. booking.quantity bleibt die Anzahl der Artikel; booking.quota_quantity gibt die belegten Plätze an. Bei Mehrpersonenprodukten oder Waren können diese Werte voneinander abweichen. previous_attributes ist eine historische Schätzung für den ursprünglichen POS, der durch seine pos_id identifiziert wird, und keine frühere Momentaufnahme der Empfängerkapazität. Berechnen Sie die Verfügbarkeit weder durch Subtrahieren der Buchungsmenge noch durch Vergleich der beiden Attributobjekte.

Buchungs- und Ereigniskennungen bleiben bei Wiederholungen gleich, während sich die aktuelle Kapazität ändern kann. Verhindern Sie anhand der Ereigniskennung, dass Buchungsaktionen mehrfach ausgeführt werden. Wenn Ihr Empfänger Kapazitätsmeldungen zur späteren Verarbeitung einreiht, behalten Sie die Verarbeitungsreihenfolge von Buchungs- und Kontingentereignissen für jeden öffentlichen Termin und POS bei oder fragen Sie das Angebot vor der Übernahme der Verfügbarkeit erneut ab. Eine erfolgreiche HTTP-Antwort bestätigt den Empfang, nicht die Anwendung der Kapazität im externen System.

Das Verkaufsfenster steuert neue externe Verkäufe. Der berechtigte Import bereits bezahlter Vorgänge mit erzwungener Buchung bleibt möglich.

Lieferungen überprüfen

Jede Zustellung erfolgt als JSON-POST-Anfrage. Es gibt keine universelle Hülle: Scan-, Vorgangs- 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. Scan-Testereignisse verwenden den kanonischen Zustellungsweg, enthalten data.sample: true und X-Toucantix-Webhook-Sample: true und umgehen die Filter des Endpunkts. Sie werden nur an den ausgewählten Endpunkt gesendet; verwenden Sie einen tatsächlichen Scan, um die Filter zu prüfen. Andere Testereignisse verwenden den Legacy-Zustellungsweg. Ihr Textkörper und ihre wegspezifischen Header können daher von der produktiven Zustellung desselben Ereignisses abweichen. Verwenden Sie Testereignisse für die Verbindung und Signaturprüfung und richten Sie Ihren Parser nach der produktiven Variante aus der Referenz aus.

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

Aufbewahrung von Diagnosedaten

Bewahren Sie eine Kopie der empfangenen Webhook-Inhalte in Ihrem eigenen System auf, falls Sie ein Langzeitarchiv der Übermittlungen benötigen. Nach erfolgreicher Verarbeitung und nach Ablauf von mindestens 90 Tagen ohne weitere Änderungen kann KORONA Event doppelte Kopien der ursprünglichen KORONA.entry-Daten sowie die gespeicherten Anfrage- und Antwortdetails erfolgreicher Integrationsübermittlungen entfernen. Erfolgreich verarbeitete eingehende Einlassereignisse können auch leere rawPayload- und normalizedPayload-Objekte zurückgeben; payloadCompactedAt gibt an, wann diese Diagnosekopien abgelaufen sind.

Ereignis-IDs, Schutz vor doppelter Zustellung, normalisierte Integrationsereignisse und der Scanverlauf von Tickets stehen weiterhin zur Verfügung. Bei ausstehenden, fehlgeschlagenen, ungelösten oder auf einen erneuten Versuch wartenden Vorgängen bleiben die für die Wiederherstellung erforderlichen Nutzdaten erhalten. Das Ablaufen der Gültigkeitsdauer der Nutzdaten hat keinen Einfluss auf den JSON-Body, der bereits an Ihren Endpunkt übermittelt wurde.

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