Daten mit Webhooks an Ihre Systeme senden

Ein Webhook sendet Daten an eine URL Ihrer Wahl, sobald etwas passiert, zum Beispiel wenn jemand an einer Kampagne teilnimmt oder einen Gewinn erhält. Das System, das die Daten empfängt, richtet Ihre Entwicklerin oder Ihr Entwickler ein.

Webhooks sind in den Plänen mit Webhooks & API enthalten (ab Basic).

Kampagnen-Webhooks oder Konto-Webhooks?

• Kampagnen-Webhooks richten Sie im Kampagnen-Editor ein, und sie werden nur für diese Kampagne ausgelöst. Sie haben die Ereignisse „Jedes Mal, wenn ein Lead an einer Kampagne teilnimmt“ und „Wenn ein Lead einen Gewinn erhält“ sowie die meisten Optionen.
• Konto-Webhooks richten Sie unter Einstellungen > Webhooks ein. Sie haben das Ereignis „Wenn ein neuer Lead erstellt wird“: Es wird einmal pro Person ausgelöst, wenn sie zum ersten Mal zu Ihren Leads hinzugefügt wird, egal aus welcher Kampagne sie kommt.

Einer Kampagne einen Webhook hinzufügen

1. Öffnen Sie die Kampagne im Editor und gehen Sie zu Verbinden > Webhooks.
2. Klicken Sie auf Webhook hinzufügen.
3. Geben Sie die Payload-URL ein. Sie muss mit https beginnen: „Wir unterstützen Webhooks nur über HTTPS, damit die gesendeten Daten sicher bleiben.“
4. Wählen Sie den Inhaltstyp: application/json oder application/x-www-form-urlencoded.
5. Wählen Sie die Methode. Das Formular steht zunächst auf GET, das die Daten in der URL sendet. Wählen Sie POST, um sie im Body zu senden. Das erwarten die meisten Systeme.
6. Wählen Sie unter Authentifizierung (nur bei POST) Basic Auth, wenn Ihre URL einen Benutzernamen und ein Passwort braucht, und füllen Sie Benutzername und Passwort aus. Andernfalls lassen Sie Keine stehen.
7. Geben Sie ein Secret ein, um die Anfragen zu signieren (empfohlen). Siehe „Die Signatur prüfen“ weiter unten.
8. Schalten Sie Antworttext protokollieren ein, wenn Sie sehen möchten, was Ihr System antwortet. „Aktivieren, um den Antwortinhalt zur Fehlersuche zu speichern.“
9. Lassen Sie Aktiv eingeschaltet. „Wir liefern Ereignisse nur, wenn der Webhook aktiv ist.“
10. Wählen Sie das Ereignis: „Jedes Mal, wenn ein Lead an einer Kampagne teilnimmt“ oder „Wenn ein Lead einen Gewinn erhält“.
11. Schalten Sie Eigener Payload ein, wenn Sie die Felder selbst festlegen möchten (siehe unten).
12. Klicken Sie auf Webhook hinzufügen. Sie sehen „Webhook hinzugefügt“.

Das Panel Webhooks listet die Webhooks der Kampagne mit Aktiv oder Inaktiv auf, und mit Letzte Zustellung fehlgeschlagen, wenn die letzte Anfrage fehlgeschlagen ist. Über Aktionen können Sie einen Webhook Bearbeiten, Zustellungen ansehen oder Löschen. Wenn Sie einen Webhook bearbeiten, lassen Sie Secret leer, um das bisherige zu behalten.

Einen Konto-Webhook hinzufügen

1. Gehen Sie zu Einstellungen > Webhooks (unter Entwickler). Ihre Webhooks stehen unter Meine Webhooks (oder unter dem Namen der jeweiligen Lead-Liste, wenn Sie mehrere haben).
2. Klicken Sie auf die Karte mit dem Plus, um einen Webhook hinzuzufügen. Im Dialog Webhook hinzufügen steht „Senden Sie eine Anfrage an eine externe URL, sobald ausgewählte Ereignisse eintreten.“
3. Füllen Sie wie oben Payload-URL, Inhaltstyp („Inhaltstyp des Webhooks auswählen“), Methode und Secret aus.
4. Wählen Sie unter Welche Ereignisse sollen den Webhook auslösen? „Wenn ein neuer Lead erstellt wird“.
5. Haken Sie „Ja, ich möchte einen eigenen Payload festlegen (nur für fortgeschrittene Benutzer)“ an, wenn Sie eigene Felder möchten.
6. Haken Sie bei Bedarf Antworttext protokollieren an („Dieser Webhook protokolliert den Antworttext“), und lassen Sie Aktiv angehakt („Wir übermitteln Ereignisdetails, wenn dieser Hook ausgelöst wird“).
7. Klicken Sie auf Webhook hinzufügen.

Klicken Sie auf einen Webhook, um ihn zu ändern (Änderungen speichern), ein Neues Secret festzulegen, Zustellungen anzeigen zu öffnen oder ihn mit Webhook löschen zu entfernen („Diese Aktion kann nicht rückgängig gemacht werden!“).

Was gesendet wird

Standardmäßig enthält der Body ein event (den Namen des Ereignisses: lead_created_on_campaign, new_campaign_winner oder lead_created) und ein data-Objekt:

• campaign: id und name der Kampagne (Kampagnen-Webhooks)
• lead: die Formularfelder des Leads mit ihrem Feldschlüssel (zum Beispiel first_name), dazu id, phone_number und created_at
• lead.permissions: für jede Einwilligungs-Checkbox, ob sie angenommen wurde, der Text, das Datum und die IP-Adresse (Kampagnen-Webhooks)
• participant: der channel, über den die Person kam, und wann sie teilgenommen hat (Kampagnen-Webhooks)
• quiz: die Antworten auf benannte Quizfragen, zusätzlich unter lesbaren Namen, die mit „Simple“ beginnen
• prize: id, name, value und coupon_code des Gewinns und wann er gewonnen wurde (Gewinner-Webhooks)

Leere Werte werden weggelassen, ebenso Einwilligungen, die nicht angenommen wurden. Mit der Methode GET werden dieselben Daten als Query-Parameter in der URL gesendet.

Eigener Payload

Ist Eigener Payload eingeschaltet, werden nur die Felder gesendet, die Sie wählen, und es gibt keine event-Hülle.

1. Klicken Sie unter Datenzuordnung auf Zuordnung hinzufügen.
2. Geben Sie den Feldname ein, den Ihr System erwartet. Verwenden Sie Buchstaben, Ziffern, Bindestriche und Unterstriche.
3. Wählen Sie das Scratcher-Feld, das gesendet werden soll („Gruppe → Feld“), oder Benutzerdefinierter Wert und geben Sie einen festen Wert ein.
4. Wiederholen Sie das für jedes Feld. Entfernen Sie eine Zeile mit dem Papierkorb (Entfernen bzw. Datenzuordnung entfernen).

Die Signatur prüfen

Wenn Sie ein Secret festlegen, hat jede Anfrage einen Header X-Hub-Signature: sha1= gefolgt von einem HMAC-SHA1-Hash des JSON-kodierten Payloads (des oben beschriebenen Bodys), mit Ihrem Secret als Schlüssel. Berechnen Sie auf Ihrer Seite denselben Wert und vergleichen Sie, um sicherzugehen, dass die Anfrage von Scratcher kam.

Zustellungen und Wiederholungen

• Antwortet Ihre URL nicht oder gibt sie einen Fehler zurück (Status 400 oder höher), versucht Scratcher es zweimal erneut: nach 5 Sekunden und nach einer Minute.
• Weiterleitungen werden nicht verfolgt. Verwenden Sie also die endgültige URL.
• Öffnen Sie die Zustellungen (Zustellungen ansehen in der Kampagne, Zustellungen anzeigen bei Konto-Webhooks), um jede Anfrage und Antwort zu sehen. Jede Zustellung zeigt ihre ID, die Anfrage und die Antwort mit Statuscode (und den Antwortinhalt, wenn Sie ihn protokollieren). Mit kopieren kopieren Sie einen Payload.
• Schalten Sie Nur fehlgeschlagene Zustellungen anzeigen ein, um nur die Probleme zu sehen. Oben steht „Fehlgeschlagene Zustellungen in den letzten 60 Tagen“.
• Klicken Sie auf Erneut versuchen, um eine Zustellung noch einmal zu senden: „Der Webhook wird erneut gesendet.“
• „Webhook-Zustellprotokolle werden 60 Tage lang aufbewahrt.“

Fehlerbehebung

• „... muss HTTPS verwenden.“: Die Payload-URL beginnt mit http. Verwenden Sie https.
• Jede Zustellung schlägt ohne Antwort fehl: Die URL ist aus dem Internet nicht erreichbar, zum Beispiel eine lokale oder interne Adresse. Verwenden Sie eine öffentliche URL.
• Ihr System erhält keine Daten: Die Methode ist GET, die Daten stehen also in der URL. Wechseln Sie zu POST.
• Ein Feld, das Ihr System erwartet, fehlt: Es war leer, oder die Einwilligung wurde nicht angenommen. Lassen Sie Ihr System fehlende Felder als leer behandeln.