Webhooks einrichten und prüfen

Ein Webhook schickt jeden neuen Eintrag automatisch als JSON an eine Webadresse, zum Beispiel an Zapier, Make, n8n oder dein eigenes System. Funnelforms signiert jeden Aufruf, sodass der Empfänger prüfen kann, dass er von deiner Website kommt.

Voraussetzungen

• Funnelforms Pro. In Funnelforms Free ist diese Funktion nicht enthalten. Free bietet Webhook bei Aktion hinzufügen nicht an und nennt Webhooks im Hinweis mit dem Abzeichen Pro; auch den Reiter Schnittstellen in den Einstellungen gibt es nur in Pro.
• Du hast das Recht, Einträge zu sehen. Ohne dieses Recht kannst du die Aktion vorbereiten; jemand mit dem Recht veröffentlicht sie.
• Der Empfänger hat eine Webadresse, die Aufrufe per POST annimmt.
• Für das Webhook-Geheimnis brauchst du das Recht, die Einstellungen zu ändern.

Wo finde ich die Funktion?

• Aktion: Formular im Editor öffnen, im Arbeitsbereich Aufbau auf den Kontaktschritt klicken, rechts den Reiter Nach dem Absenden öffnen und unter Aktionen bei Aktion hinzufügen den Eintrag Webhook wählen.
• Geheimnis zur Signatur: Funnelforms → Einstellungen → Schnittstellen, Karte Webhooks.

Funktionen im Überblick

• Webadresse: Empfänger der Einträge. Der Hinweis darunter: „Empfängt jeden Eintrag als JSON, signiert mit dem Webhook-Geheimnis der Website.“
• Format: Funnelforms 3 (Pro) oder Funnelforms 4 (Zaps und Szenarien aus der Online-Version).
• Signatur mit drei Headern: Zeitstempel, Signatur und Zustellungs-ID.
• Bis zu drei Versuche pro Zustellung.
• Wann (sofort oder nach der Zahlung) und Für Einträge aus (bestimmter Kontaktschritt oder Jedem Kontaktschritt).

Schritt-für-Schritt-Anleitung

1. Öffne das Formular im Editor, klicke auf den Kontaktschritt und dann rechts auf den Reiter Nach dem Absenden.
2. Wähle bei Aktion hinzufügen den Eintrag Webhook.
3. Trage bei Webadresse die Adresse des Empfängers ein, beginnend mit https://.
4. Wähle bei Format das Format, das dein Empfänger erwartet.
5. Veröffentliche das Formular mit Veröffentlichen.
6. Schicke einen Testeintrag ab und prüfe beim Empfänger, ob der Aufruf ankommt.
7. Möchtest du die Signatur prüfen, öffne Funnelforms → Einstellungen → Schnittstellen, Karte Webhooks, und kopiere das Geheimnis aus dem Feld Webhook-Geheimnis.
8. Hinterlege das Geheimnis beim Empfänger und prüfe die Signatur, wie unten beschrieben.

Erklärungen

Was wird gesendet?

Funnelforms sendet einen POST-Aufruf mit JSON im Body und den Headern Content-Type: application/json und Accept: application/json. Der Empfänger muss innerhalb von 15 Sekunden antworten.

Format „Funnelforms 3 (Pro)“ entspricht dem Webhook von Funnelforms 3. Der JSON-Body enthält unter anderem diese Schlüssel:

• form_id, lead_id (die Nummer des Eintrags) und lead_timestamp
• analytics_data mit query_string und url
• questions (Frage und Antwort), all_questions_by_id, all_question_data
• contact_form (Kontaktfelder nach Variablenname), all_contact_form_data
• hidden_fields und calculationData

Format „Funnelforms 4“ sendet die Nutzlast der Online-Version von Funnelforms 4 mit denselben Schlüsseln und Typen, damit bestehende Zaps und Szenarien weiterlaufen. Der Body enthält timestamp, id, form, formFields, analytics, formResponseId, formResponsesByFieldId, formResponsesByWebhookFieldId und allQuestionData.

• Felder heißen wie ihr Variablenname, Kontaktfelder „field-“ plus Name.
• Gib den Feldern die IDs aus Funnelforms 4 als Variablennamen, dann laufen bestehende Zaps weiter.
• Angaben, die Funnelforms 5.0 nicht speichert (IP-Adresse, Bildschirmgröße, Browser-Einstellungen), sind null.

Wie prüfe ich die Signatur?

Jeder Aufruf trägt diese Header:

• X-Funnelforms-Timestamp: Unix-Zeit des Versands.
• X-Funnelforms-Signature: v1= plus der HMAC-SHA256 (hexadezimal) aus Zeitstempel.Body mit dem Webhook-Geheimnis der Website.
• X-Funnelforms-Delivery: Nummer der Zustellung. Bei Wiederholungen bleibt sie gleich.

Beispiel in PHP:

$body      = file_get_contents( 'php://input' );
$timestamp = $_SERVER['HTTP_X_FUNNELFORMS_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_FUNNELFORMS_SIGNATURE'] ?? '';
$expected  = 'v1=' . hash_hmac( 'sha256', $timestamp . '.' . $body, $secret );
if ( ! hash_equals( $expected, $signature ) ) {
	http_response_code( 401 );
	exit;
}

Nimm den unveränderten Body, wie er ankommt. Prüfe zusätzlich, dass der Zeitstempel nicht zu alt ist, und merke dir die Zustellungsnummer, um Doppelte zu erkennen. Das Geheimnis wird beim ersten Gebrauch angelegt und beginnt mit whsec_.

Was passiert bei Fehlern und Wiederholungen?

Funnelforms zählt nur eine Antwort mit Status 200 bis 299 als Erfolg. Bei jeder anderen Antwort und bei Verbindungsfehlern versucht es den Aufruf insgesamt dreimal: nach einer und nach vier Minuten erneut. Danach steht die Zustellung auf Fehlgeschlagen mit einem Fehlercode wie http_500. Der Eintrag selbst bleibt gespeichert.

Du siehst die Zustellungen im Eintrag unter Gesendet an und in der Liste unter Funnelforms → Einstellungen → E-Mail im Abschnitt Mails und Zustellungen. Mit Erneut senden … im Eintrag schickst du den Webhook nochmal; das ist eine neue Zustellung mit neuer Zustellungsnummer.

Was passiert, wenn ich das Geheimnis erneuere?

Mit Neues Geheimnis erzeugen ersetzt Funnelforms das Geheimnis sofort und meldet „Webhook-Secret erneuert“. Empfänger, die die Signatur prüfen, brauchen danach das neue Geheimnis.

Was passiert mit Double-Opt-in?

Ist beim Formular Double-Opt-in aktiv, wartet der Webhook, bis der Besucher seine Adresse bestätigt hat.

Best Practices

• Prüfe auf Empfängerseite die Signatur und den Zeitstempel.
• Antworte schnell mit Status 200 und arbeite länger dauernde Schritte im Hintergrund ab.
• Nutze die Zustellungsnummer, um doppelte Aufrufe zu erkennen.
• Gib Feldern sprechende, feste Variablennamen, damit sich Zuordnungen im Empfänger nicht ändern.

Troubleshooting

Tipps

• Einen Test ohne eigenen Empfänger kannst du mit einem Dienst machen, der Aufrufe anzeigt. Gib dort keine echten Kundendaten ein.
• Brauchst du statt Push-Aufrufen eine Abfrage per Zugangstoken, siehe Automatisierung mit Zugangstoken.

FAQ

Kann ich mehrere Webhooks pro Formular einrichten? Ja. Füge die Aktion Webhook mehrfach hinzu, jeweils mit eigener Webadresse.

Wird jeder Aufruf signiert? Ja, immer. Auch Empfänger, die nicht prüfen, funktionieren weiter, weil der Body unverändert bleibt.

Wie oft versucht Funnelforms es? Dreimal pro Zustellung, mit einer und vier Minuten Pause.

Kann ich einen Webhook von Funnelforms 3 weiter nutzen? Ja. Das Format „Funnelforms 3 (Pro)“ entspricht dem Body von Funnelforms 3.

Gibt es Webhooks in Funnelforms Free? Nein. Hat ein Formular einen Webhook und die Website nutzt Free, führt Free ihn nicht aus; im Eintrag steht er als „Übersprungen“.

Weiterführende Artikel

• Automatisierung mit Zugangstoken
• Einträge verwalten
• E-Mails kommen nicht an