Individuelle Webhooks

So funktioniert es

Bei jeder Einreichung sendet formbase einen JSON-Body per POST an deine Webhook-URL. Der Request wird mit HMAC-SHA256 signiert, bei Fehlern wiederholt und im Ereignisprotokoll der Integration erfasst. Diese Seite behandelt die Einrichtung. Die genaue Nutzlast, die Header und der Signaturalgorithmus stehen in der Webhook-Referenz.

Webhook hinzufügen

1. 1

   Formular-Integrationen öffnen

   Formular → Einstellungen → Integrationen → Webhook.

2. 2

   URL

   Gib Host und Pfad ein — das Präfix https:// ist im Eingabefeld fest vorgegeben. Reines http:// wird nur für localhost während der Entwicklung akzeptiert.

3. 3

   Zuordnung

   Lass sie leer, um jedes Feld zu senden. Füge Zeilen hinzu, um nur diese Felder zu senden, unter dem JSON-Schlüssel deiner Wahl. Die Zuordnung formt answers und display gemeinsam, ein umbenannter Schlüssel ist also in beiden umbenannt. Der vollständige Request unter der Zuordnung aktualisiert sich, während du sie bearbeitest.

4. 4

   Header

   Ein Signing-Secret beginnend mit whsec_ wird für dich generiert. Es kann nach der Erstellung nicht geändert werden. Füge im selben Schritt bis zu 5 benutzerdefinierte Header hinzu, die dein Endpunkt braucht, etwa ein Autorisierungs-Token, und schalte Feldliste mit jedem Ereignis senden ein, wenn dein Empfänger fields.list nicht aufrufen kann. Content-Type wird automatisch gesetzt und kann nicht überschrieben werden.

5. 5

   Fertigstellen

   Drücke Testereignis senden, um eine synthetisierte Beispieleinreichung per POST zu senden, dann Integration erstellen.

Welche URLs formbase akzeptiert

• Überall https://, oder http:// für localhost und *.localhost während der Entwicklung.

• Keine Zugangsdaten in der URL, und höchstens 2.048 Zeichen.

• Keine privaten oder internen Adressen. Der Hostname wird unmittelbar vor jeder Zustellung aufgelöst und erneut geprüft, sodass ein DNS-Eintrag, der nach der Einrichtung auf eine interne Adresse umgebogen wird, weiterhin abgelehnt wird.

Eine abgelehnte URL ist ein Konfigurationsproblem, kein vorübergehendes: Die Zustellung schlägt endgültig fehl, statt wiederholt zu werden.

Was du erhältst

Jeder Request ist derselbe Ereignis-Umschlag — id, type, createdAt, apiVersion, test und data. In data stehen das Formular, die Einreichung (ID, E-Mail der befragten Person, Zeitpunkt der Einreichung, PDF-Link, Sprache), ein answers-Objekt, das nach Feldschlüssel benannt ist, und ein display-Objekt mit denselben Schlüsseln als lesbarer Text. Jede Antwort erscheint einmal, in jeder Map.

Die vollständige Nutzlastform, answers und display, und wie eine Wiederholungsgruppe dargestellt wird, findest du in der Referenz.

Um den genauen Body für dein Formular als Vorschau zu sehen, öffne die Integration und klappe Beispiel-Nutzlast unter dem Signing-Secret auf. Sie rendert deine aktuelle Zuordnung mit Beispielantworten.

Signaturen prüfen

Jeder Request enthält einen X-formbase-Signature-Header: t=TIMESTAMP,sha256=HEX, ein HMAC-SHA256 von TIMESTAMP.BODY, berechnet mit deinem Signing-Secret. Das Secret selbst wird nie gesendet. Die Referenz enthält ein kopierbares Prüf-Snippet.

Ereignisse bei abgebrochenen Antworten

Individuelle Webhooks werden nur bei abgeschlossenen Einreichungen und Bearbeitungen ausgelöst — nie bei abgebrochenen Entwürfen. Ein individueller Webhook ist der einzige Empfänger, der beide bekommt: Ein Zapier-, Make- oder n8n-Abonnement wählt entweder erste Einreichungen oder Bearbeitungen, nie beide. Nutze für abgebrochene Entwürfe einen Anbieter mit einem Schritt Abgebrochene Einreichungen: Google Sheets, Airtable, Notion, Slack, Discord, Linear oder GitHub Issues. Jeder hat ein eigenes Leerlauffenster und, sofern zutreffend, eine eigene Vorlage. Dieser Schritt erfordert Pro oder Business.

Wiederholungsversuche und Fehler

• Eine Zustellung gilt bei jedem 2xx als erfolgreich.

• Bis zu 5 Versuche: Der erste erfolgt sofort, Wiederholungen warten mindestens 1, 2, 4 und 8 Minuten. formbase sucht alle 30 Minuten nach fälligen Wiederholungen, sodass der letzte Versuch etwa zwei Stunden nach dem ersten erfolgt. Ein Retry-After-Header bei einem 429 oder 5xx wird befolgt, wenn er eine längere Wartezeit verlangt.

• 429, 5xx, Timeouts und Verbindungsfehler werden wiederholt. Jeder andere 4xx-Fehler schlägt sofort fehl.

• Nach 5 aufeinanderfolgenden Fehlern pausiert die Integration automatisch, und die Person, die sie eingerichtet hat, erhält eine E-Mail. Behebe den Endpunkt und drücke dann Fortsetzen.

• 401, 403 und 404 stoppen die Integration sofort mit einem Fehlerstatus und derselben E-Mail — ohne auf fünf Fehler zu warten.

• Zustellungen, die alle 5 Versuche aufgebraucht haben, sammeln sich in einem Banner auf der Integration. Alle erneut versuchen reiht sie erneut ein und reaktiviert eine pausierte Integration.

Testen

Testereignis senden erscheint im Schritt Fertigstellen und erneut auf der gespeicherten Integration. Es sendet eine synthetisierte Beispieleinreichung per POST — “John Doe” für Text, 42 für Zahlen, john@example.com für E-Mail — signiert und mit deinen benutzerdefinierten Headern, genau wie eine echte Zustellung. Von der gespeicherten Integration aus schreibt es außerdem einen Verbindungstest-Eintrag in das Ereignisprotokoll.

Für lokale Entwicklung kannst du deinen Dev-Server mit einem Tunnel zugänglich machen:

# ngrok
ngrok http 3000

# cloudflare tunnel

cloudflared tunnel --url http://localhost:3000

FAQ

Nächste Schritte