Webhooks
Hilfeartikel können unvollständig oder veraltet sein – sie können sich aufgrund häufiger Updates und automatisierter Übersetzung von der App unterscheiden. Im Zweifelsfall wenden Sie sich bitte an den Support.
Ein Webhook teilt Ihrem eigenen System den Moment mit, in dem in EventMann etwas passiert, damit Sie nicht ständig nachfragen müssen. EventMann sendet bei jedem abonnierten Ereignis eine HTTPS-Anfrage an eine Adresse Ihrer Wahl: eine Buchung wird bestätigt, eine Bestellung wird erstattet, ein Event geht live. Webhooks finden Sie im Reiter Webhooks unter Integrationen in der Seitenleiste.
- Öffnen Sie Integrationen und klicken Sie auf den Reiter Webhooks.
- Klicken Sie auf Webhook hinzufügen, um einen Endpunkt anzulegen.
- Die Spalte Status zeigt Aktiv oder Deaktiviert, zusammen mit dem HTTP-Status des letzten Versuchs.
- Ein deaktivierter Endpunkt bietet Wieder aktivieren an.
Einen Endpunkt hinzufügen
- Geben Sie ihm einen Namen zur eigenen Verwendung.
- Tragen Sie die Endpunkt-URL ein, eine öffentliche Webadresse, die einen POST annimmt.
- Haken Sie unter Veranstaltungen abonnieren die gewünschten Ereignisse an. Mindestens eines ist erforderlich.
- Klicken Sie auf Webhook hinzufügen. Ein 64-stelliger Signierungsschlüssel wird für Sie erstellt.
Ereignisse, die Sie auswählen können
Das Formular listet fünfzehn Ereignisse auf, und jedes davon wird gesendet:
| Ereignis | Gesendet, wenn |
|---|---|
booking.created | Eine Bestellung entsteht: beim Checkout für kostenlose Bestellungen und Genehmigungsanfragen, beim Zahlungsschritt für bezahlte. |
booking.confirmed | Eine Bestellung wird bestätigt: bezahlt, kostenlos oder manuell erfasst. |
payment.received | Eine Zahlung wird verbucht. Sie wird zusammen mit booking.confirmed gesendet, auch bei kostenlosen Bestellungen. |
booking.cancelled | Eine Bestellung wird storniert: vom Käufer, von Ihnen oder Ihrem Team oder vom EventMann-Support. cancelled_by zeigt, wer (attendee, organizer oder admin). |
booking.refunded | Eine Bestellung wird vollständig erstattet. |
payment.refunded | Eine Erstattung wird verbucht, auch Teilerstattungen. Eine pro Erstattung, mit ihrem Betrag. |
event.created | Ein Event wird angelegt, egal wie (Assistent, Kopie, wiederkehrende Serie). |
event.updated | Die Details eines Events ändern sich: Titel, Beschreibung, Bild, Termine, Veranstaltungsort oder Adresse, Online-Link, Verkaufszeitraum, Sichtbarkeit. changed listet die Felder. Eine Statusänderung ist kein Update; sie hat eigene Ereignisse. |
event.published | Ein Event geht live. |
event.cancelled | Sie sagen ein Event ab. |
ticket.checked_in | Ein Ticket wird am Eingang zugelassen: gescannt, manuell eingegeben, gesammelt eingecheckt, aus einem Offline-Scanner synchronisiert oder an der Abendkasse verkauft und zugelassen. Ein Ticket auszuchecken oder eine Nichterscheinung zu markieren löst kein Ereignis aus, ebenso wenig die Aktion Einchecken in der Bestellliste, die ganze Bestellungen ohne Scan als angekommen markiert. |
staff.assigned | Jemand wird Mitarbeiter eines Events: Sie genehmigen seine Bewerbung, oder er nimmt eine Einladung für dieses Event an. |
staff.checked_in | Ein Mitarbeiter stempelt für eine Schicht ein. |
vendor.assigned | Sie weisen einem Event einen Lieferanten zu. |
vendor.invoice_submitted | Ein Lieferant reicht eine Rechnung für eine Zuweisung ein. |
Es gibt keine Auszahlungsereignisse. Stripe überweist Ihre Ticketeinnahmen direkt auf Ihr eigenes Konto, und EventMann erstellt diese Auszahlungen nicht und sieht sie auch nicht.
Wie eine Zustellung aussieht
Jede Zustellung ist ein POST mit einem JSON-Body in dieser Form: event (der Name), data (die Details), timestamp und delivery_id. Die Daten für booking.confirmed enthalten die Bestell-ID, Referenz, Status, Gesamtbetrag, Name und E-Mail-Adresse des Teilnehmers, Event-ID und den Zeitpunkt der Bestätigung. booking.created ergänzt den Event-Titel und enthält stattdessen den Zeitpunkt der Erstellung. payment.received enthält Buchungs-ID, Betrag, Zahlungsanbieter, Transaktions-ID und Zeitpunkt.
Die Anfrage trägt drei Header: X-Webhook-Event, X-Webhook-Delivery-Id und X-Webhook-Signature. Die Signatur ist ein HMAC-SHA256 des rohen Anfrage-Bodys in hexadezimaler Darstellung, berechnet mit dem Signierungsschlüssel Ihres Endpunkts. Berechnen Sie sie auf Ihrer Seite aus dem rohen Body neu und vergleichen Sie sie, bevor Sie einer Nutzlast vertrauen.
Einen Endpunkt prüfen
- Klicken Sie auf Test senden, um einen Beispiel-
pingan Ihre Adresse zu senden und das Ergebnis sofort zu sehen. - Abonnierte Ereignisse zeigt, was der Endpunkt empfängt. Mit Bearbeiten ändern Sie Name, Adresse oder Ereignisse.
- Der Signierungsschlüssel ist verborgen; klicken Sie auf Anzeigen, um ihn einzublenden.
- Letzte Lieferungen listet die letzten Versuche mit Ereignis, Status, HTTP-Code, Dauer und Zeit. Alle anzeigen zeigt mehr.
Wiederholungen, Fehler und automatische Abschaltung
- Nur eine Antwort mit 2xx gilt als zugestellt. Eine Weiterleitung oder jede andere Antwort ist ein Fehler; Weiterleitungen werden nicht verfolgt.
- Eine fehlgeschlagene Zustellung wird bis zu fünfmal versucht, mit Wartezeiten von 10, 30 und dann 60 Sekunden zwischen den Versuchen.
- Schlagen alle Versuche für ein Ereignis fehl, steigt der Fehlerzähler des Endpunkts um eins. Zehn Fehler innerhalb einer Stunde pausieren die Zustellung an diesen Endpunkt für fünf Minuten; Zustellungen warten die Pause ab.
- Wird die Pause ausgelöst oder überschreitet der Fehlerzähler zehn, wird der Endpunkt abgeschaltet, und Sie erhalten eine Benachrichtigung mit seinem Namen.
- Eine Adresse, die auf ein privates oder internes Netzwerk zeigt, wird beim Zustellversuch abgelehnt. Der Test zeigt „Blockiert“, und eine echte Zustellung schaltet den Endpunkt ab.
- Der Zustellverlauf wird 30 Tage lang aufbewahrt.
- Ein deaktivierter Endpunkt zeigt Dieser Endpunkt ist deaktiviert mit dem Grund.
- Beheben Sie den Fehler auf Ihrer Empfängerseite und klicken Sie dann auf Wieder aktivieren. Der Fehlerzähler wird zurückgesetzt; Adresse und Schlüssel bleiben gleich. Das Bearbeiten von Name oder Adresse aktiviert den Endpunkt nicht wieder.
- Erneut versuchen bei einer fehlgeschlagenen Zustellung sendet dieses Ereignis erneut als neue Zustellung an Ihre derzeit aktiven Endpunkte, die es abonnieren. Dazu gehören auch Ihre anderen Endpunkte, sodass sie es möglicherweise zweimal erhalten.
Gut zu wissen
- Der Webhook-Versand läuft in einer eigenen Warteschlange, sodass ein langsamer Empfänger weder Buchungen noch Ticket-E-Mails verlangsamen kann.
- Wenn Sie ein Ereignis abwählen, wird es stillschweigend beendet. Sie erhalten keine Mitteilung, dass Sie es nicht mehr empfangen.
- Wenn Sie ein Tool wie Zapier mit einem EventMann-API-Token verbinden, erscheinen die von ihm erstellten Abonnements hier ebenfalls, benannt nach dem Ereignis.
- Webhooks senden Name und E-Mail-Adresse des Teilnehmers jeder Bestellung an Ihren Server. Stellen Sie sicher, dass die Adresse Ihnen gehört und dass Sie diese Daten verarbeiten dürfen.
Fehlerbehebung
- Zustellungen sind gestoppt, und Sie sehen keinen Fehler — öffnen Sie den Endpunkt. Ist er deaktiviert, beheben Sie den Empfänger und klicken Sie auf Wieder aktivieren.
- Die Signatur stimmt nie überein — berechnen Sie den Hash über den exakten rohen Body, nicht über eine neu kodierte Kopie, mit dem Schlüssel von der Endpunktseite, und vergleichen Sie hexadezimalen Text.
- Der Test funktioniert, aber echte Ereignisse kommen nicht an — prüfen Sie, ob das Ereignis an diesem Endpunkt angehakt ist und ob das Geschehene zur Spalte „Gesendet, wenn“ in der Tabelle passt.
- Sie erhalten dasselbe Ereignis zweimal — Sie haben Erneut versuchen gedrückt, oder zwei Endpunkte abonnieren es. Verwenden Sie die Zustell-ID, um Wiederholungen zu ignorieren.