Zum Inhalt springen
Leat Help Center

Webhooks: Ereignisse aus Leat an Ihr eigenes System senden

Ein Webhook-Abonnement sorgt dafür, dass Leat jedes Mal eine URL auf Ihrer Seite aufruft, wenn ein bestimmtes Ereignis eintritt: Ein Kontakt wird angelegt oder aktualisiert, Punkte werden gutgeschrieben, ein Voucher wird eingelöst. Leat sendet eine POST-Anfrage mit den Daten zu diesem Ereignis, signiert sie und wiederholt sie, wenn Ihr Endpunkt nicht antwortet.

So bekommen Sie Daten aus Leat heraus und in ein anderes System hinein. Nutzen Sie es immer dann, wenn die Frage lautet: „Wie sende ich X an mein System, wenn Y passiert?“

Webhook-Abonnement oder die Webhook-Aktion einer Automatisierung?

Auch eine Automatisierung hat eine Aktion Webhook, und sie wirkt wie der schnellere Weg. Um ein anderes System aktuell zu halten, ist sie aber nicht das richtige Werkzeug. Im Vergleich zu einem Abonnement gilt für den Webhook einer Automatisierung:

  • er ist nicht signiert, Ihr Endpunkt kann also nicht prüfen, ob die Anfrage von Leat kommt
  • er wird nicht wiederholt: Ist Ihr Endpunkt nicht erreichbar, geht dieser Aufruf verloren
  • eine Fehlerantwort Ihres Endpunkts zählt trotzdem als gesendet
  • es gibt keinen Zustellverlauf, nur ein Schrittergebnis in der Ausführung der Automatisierung
  • er wird nur für Kontakte ausgelöst, die die Filter und die Einstellungen zur erneuten Teilnahme der Automatisierung passieren

Nutzen Sie die Aktion Webhook nur, wenn der Aufruf ein Schritt in einem Ablauf ist, der etwas braucht, das ein Abonnement nicht kann, etwa eine Verzögerung, eine Verzweigung oder einen Filter. Für alles andere erstellen Sie ein Webhook-Abonnement, wie unten beschrieben.

Bevor Sie beginnen: eine Private App

Webhook-Abonnements gehören zu einer Integration. Für Ihr eigenes System ist das eine Private App:

  1. Gehen Sie zu Apps und dann zu Integrationen.
  2. Klicken Sie auf der Seite Marktplatz oben rechts auf Private App erstellen.
  3. Benennen Sie sie nach dem System, das Sie verbinden, und klicken Sie auf Erstellen.

Sie landen auf der Seite der Private App. Später finden Sie sie in der Seitenleiste unter Installiert.

Auf einer Marktplatz-Integration wie Shopify oder Klaviyo lassen sich keine Webhooks erstellen. Diese Integrationen zeigen die Webhooks, die sie nutzen, auf ihrem eigenen Tab Webhooks, verwalten sie aber selbst.

Einen Webhook erstellen

  1. Öffnen Sie Ihre Private App und gehen Sie zum Tab Webhooks.
  2. Klicken Sie auf Neuer Webhook.
  3. Wählen Sie das Ereignis. Der Name wird mit dem Namen des Ereignisses vorausgefüllt, und Sie können ihn ändern.
  4. Geben Sie die URL Ihres Endpunkts ein.
  5. Klicken Sie auf Erstellen.

Der Webhook ist sofort aktiv und öffnet sich auf seiner eigenen Seite.

Eine Private App kann einen Webhook pro Ereignis haben. Um dasselbe Ereignis an zwei URLs zu senden, erstellen Sie eine zweite Private App.

Ereignisse, die Sie abonnieren können

Kontakte:

  • contact_created
  • contact_updated
  • contact_was_subscribed
  • contact_was_unsubscribed
  • contact_identifier_created
  • contact_identifier_updated

Treue und Stufen:

  • credit_reception_created
  • points_transaction_created
  • tier_reached
  • tier_dropped

Belohnungen, Aktionen und Vouchers:

  • reward_updated
  • reward_redeemed
  • promotion_updated
  • voucher_created
  • voucher_updated
  • voucher_expired
  • voucher_redeemed

Stempelkarten:

  • stamp_card_created
  • stamp_card_transaction_created
  • stamp_card_redeemed
  • stamp_card_redemption_reversed
  • stamp_card_expired

Die Stempelkarten-Ereignisse gibt es nur als V2-Webhooks. Siehe Ältere V1-Webhooks weiter unten.

Geschenkkarten und Prepaid:

  • giftcard_created
  • giftcard_updated
  • giftcard_transaction_created
  • prepaid_transaction_created

Bestellungen, Besuche und Buchungen:

  • order_created
  • visit_created
  • booking_created
  • booking_updated

Formulare und Empfehlungen:

  • form_submission_completed
  • referral_completed

Die Seite Webhooks in der API-Referenz unter docs.leat.com/v3 enthält für jedes Ereignis ein Beispiel-Payload.

Was Ihr Endpunkt empfängt

Jede Anfrage ist ein POST mit einem JSON-Body. Ein im Dashboard erstellter Webhook sendet immer ein Array von Ereignissen, auch wenn es nur eines ist:

{
  "batch_uuid": "…",
  "version": "V2",
  "event_type": "contact_updated",
  "count": 1,
  "events": [
    {
      "event_uuid": "…",
      "event_type": "contact_updated",
      "data": { "contact": { … } }
    }
  ]
}

Die meisten Ereignisse gehen einzeln raus, wenige Sekunden nachdem sie passiert sind. Leat wartet nicht darauf, einen Batch zu füllen. Massenvorgänge, etwa das Ausstellen von Vouchers an eine Gruppe von Kontakten, senden echte Batches mit bis zu 100 Ereignissen oder 1 MB, je nachdem, was zuerst erreicht ist.

Bei den Kontakt-Ereignissen enthält data.contact den Kontakt, wie er jetzt ist: die E-Mail-Adresse, jedes benutzerdefinierte Attribut mit seinem Wert, das Punkteguthaben mit seinen Summen, die Stufe und das Prepaid-Guthaben.

contact_updated sagt nicht, welche Attribute sich geändert haben. Es sendet den ganzen Kontakt nach der Änderung. Wenn Sie wissen müssen, was sich geändert hat, vergleichen Sie ihn mit dem, was Sie gespeichert haben.

Prüfen, ob eine Anfrage von Leat kommt

Jede Anfrage trägt einen Signature-Header. Er ist ein HMAC-SHA256 des rohen Request-Bodys als Hex-String in Kleinbuchstaben, berechnet mit Ihrem Secret.

Berechnen Sie denselben Hash über den Body genau so, wie Sie ihn empfangen haben, bevor Sie ihn parsen, und vergleichen Sie die beiden:

$expected = hash_hmac('sha256', $rawBody, $secret);

if (! hash_equals($expected, $request->header('Signature'))) {
    abort(401);
}

Ein neuer Webhook wird mit Ihrem Account-Secret signiert, das Sie unter Apps → Integrationen → Account secret in der Seitenleiste finden. Um einem einzelnen Webhook ein eigenes Secret zu geben, öffnen Sie ihn, klicken Sie auf Bearbeiten und füllen Sie Geheimnis aus. Leer lassen, um das aktuelle Geheimnis beizubehalten.

Mit einem 2xx antworten, und was passiert, wenn Sie das nicht tun

Leat wertet eine Zustellung als erfolgreich, wenn Ihr Endpunkt innerhalb von 20 Sekunden mit einem 2xx-Status antwortet. Alles andere, auch ein Timeout oder eine abgelehnte Verbindung, ist ein Fehlschlag, und Leat versucht es erneut.

Eine Zustellung bekommt insgesamt 5 Versuche. Die Wartezeiten dazwischen betragen ungefähr 1 Minute, 2 Minuten, 17 Minuten und 3 Stunden. Nach dem fünften Fehlschlag wird die Zustellung als Fehlgeschlagen markiert und nicht erneut gesendet.

Der Webhook selbst bleibt aktiv, und Sie bekommen keine Benachrichtigung. Prüfen Sie also den Verlauf, wenn Sie vermuten, dass etwas fehlt.

Ein erneuter Versuch sendet den ganzen Batch noch einmal. Speichern Sie die event_uuid jedes Ereignisses, das Sie verarbeitet haben, und überspringen Sie die, die Sie schon kennen.

Sehen, was gesendet wurde, und einen Test senden

Öffnen Sie den Webhook und gehen Sie zum Tab Verlauf. Jede Zustellung wird mit ihrem Status aufgeführt: Ausstehend, Erneuter Versuch, Erfolgreich oder Fehlgeschlagen. Außerdem sehen Sie die Anzahl der enthaltenen Ereignisse, die Anzahl der Versuche und den letzten Versuch. Klicken Sie eine Zustellung an, um den genauen Body zu sehen, der gesendet wurde, und pro Versuch den Statuscode, den Ihr Endpunkt zurückgegeben hat, und wie lange es gedauert hat.

Zustellungen werden 90 Tage aufbewahrt, die einzelnen Versuche 30 Tage.

Um Ihren Endpunkt auszuprobieren, klicken Sie auf der Seite des Webhooks auf Test. Die Schaltfläche ist nur da, solange der Webhook aktiv ist. Bei einem Kontakt-Ereignis wählen Sie den Kontakt, der gesendet werden soll. Bei jedem anderen Ereignis gilt: Der neueste passende Datensatz in Ihrem Konto wird verwendet, um die Test-Payload zu erstellen. Der Test schlägt also fehl, wenn Ihr Konto noch keinen solchen Datensatz hat. Ein Test ist eine echte Zustellung: Er erscheint im Verlauf und wird wie jede andere wiederholt.

Einen Webhook ändern, pausieren oder entfernen

  • Bearbeiten ändert den Namen, die URL und das Secret. Das Ereignis lässt sich nicht ändern, erstellen Sie für ein anderes Ereignis also einen neuen Webhook.
  • Deaktivieren stoppt die Zustellungen, bis Sie ihn wieder aktivieren. Ereignisse, die in der Zwischenzeit passieren, werden nicht nachträglich gesendet.
  • Löschen ist nur bei einem inaktiven Webhook verfügbar, deaktivieren Sie ihn also zuerst.

Wenn Sie eine Private App löschen, werden alle ihre Webhooks abgeschaltet.

Ältere V1-Webhooks

Ein Webhook, der erstellt wurde, bevor es V2 gab, zeigt V1 als Version, zusammen mit einem Hinweis, dass die Unterstützung für V1 endet. Ein V1-Webhook sendet ein Ereignis pro Anfrage statt eines Arrays und gibt Ihrem Endpunkt 3 Sekunden Zeit für die Antwort. Ereignisse, die nach V2 hinzugekommen sind, etwa die Stempelkarten-Ereignisse, haben keine V1-Version.

Die Version eines Webhooks lässt sich nicht ändern. Um umzusteigen, passen Sie Ihren Endpunkt so an, dass er ein Array von Ereignissen annimmt. Deaktivieren und löschen Sie dann den V1-Webhook und erstellen Sie einen neuen für dasselbe Ereignis, denn eine Private App kann nur einen Webhook pro Ereignis haben.

Webhooks über die API verwalten

Eine Entwicklerin oder ein Entwickler kann Webhook-Abonnements auch über die API erstellen und verwalten, unter /api/v3/oauth/clients/webhook-subscriptions. Übergeben Sie beim Erstellen "version": "V2": Ohne diese Angabe erstellt die API einen V1-Webhook. Tokens und den Rest der API finden Sie unter Eine eigene Integration mit der Leat API bauen.

Zurück zum Hilfe-Center