> Diese Seite dokumentiert den Payload-Vertrag und die REST-Abonnement-API. Um einen benutzerdefinierten Webhook für dein Formular in der > Oberfläche einzurichten, siehe Individuelle Webhooks. >
POST <your-url> mit Content-Type: application/json.
Content-Type: application/json
X-Formstep-Signature: t={timestamp},sha256={hex} — vorhanden, wenn ein Signing-Secret eingerichtet ist
(siehe unten)
X-Formstep-Event-Id und X-Formstep-Event-Type — dieselben Werte wie id und type im
Body, sodass du deduplizieren und routen kannst, bevor du parst. Ein Request-Callback sendet
dieselben zwei.
Content-Type, das sich nicht überschreiben lässt. Native Abonnements, die über webhooks.create erstellt
wurden, haben keine benutzerdefinierten Header.
Wenn du eine Webhook-Integration einrichtest, wählst du, welches Ereignis Zustellungen auslöst:
Die drei request_*-Ereignisse werden über webhooks.create abonniert und sind das, worauf die Formstep-Apps für
Zapier, Make und n8n hören. Jedes liefert denselben Umschlag, den ein Request-Callback sendet,
signiert mit dem eigenen Geheimnis des Abonnements. Testanfragen erreichen nie ein Abonnement, und requests.replayCallback{' '}
sendet nur den Callback erneut. Ein Abonnement, ein Ereignis: submission_created ist Traffic über den öffentlichen Link, und{' '}
request_completed ist Request-Traffic, ein abgeschlossener Request löst submission_created also nie aus, und ein
Formular mit beiden Abonnements erhält eine Zustellung pro Abschluss. Eine Bearbeitung erreicht ausschließlich ein{' '}
submission_updated-Abonnement, nie ein submission_created-Abonnement. Der benutzerdefinierte Webhook, der in den
Formulareinstellungen konfiguriert ist, hat keine Ereigniswahl: Er empfängt erste Einreichungen und Bearbeitungen gleichermaßen,
unterschieden durch type.
Das Feld type im JSON-Body zeigt dir an, was passiert ist:
submission.completed — eine neue abgeschlossene Einreichung
submission.updated — eine bestehende Einreichung wurde bearbeitet
submission.abandoned — eine Entwurfseinreichung wurde nach dem konfigurierten Leerlauffenster abgebrochen
Ein Request-Callback und ein request_*-Abonnement verwenden denselben Umschlag mit{' '}
request.completed, request.expired und request.canceled, sodass ein Parser alle sechs liest.
answers ist das flache {'{ field key: value }'}-Objekt, dessen Schlüssel die bei der Veröffentlichung fixierten
Feld-Schlüssel sind. Lies es, wenn ein Workflow verzweigt oder einen Wert speichert: answers.email, kein Array zu
durchlaufen. Eine Auswahlantwort ist der Schlüssel der gewählten Option — der key, den{' '}
fields.list für diese Option listet —, ist also dieselbe, unabhängig davon, in welcher Sprache die ausfüllende Person
geantwortet hat. Ein Datum ist ein ISO-String, eine Zahl eine Zahl, eine Mehrfachauswahl ein Array von Options-Schlüsseln. Unbeantwortete
Felder werden ausgelassen, nie als null gesendet.
display trägt dieselben Schlüssel mit für Menschen lesbarem Text: das Optionslabel statt seines Schlüssels, ein formatiertes
Datum, eine verbundene Liste. Lies es, wenn eine Person den Wert sehen wird — eine Slack-Nachricht, eine Tabellenzelle, eine E-Mail.
Eine Wiederholungsgruppe erscheint in answers genau einmal, unter dem eigenen Feld-Schlüssel der Gruppe, als Array von
Zeilenobjekten, deren Schlüssel die Feld-Schlüssel der einzelnen Mitglieder sind — oben answers.attendees[0].attendee_name —
und in display als eine Zeile mit verbundenen Zeilen. Ein Mitglied wird nie auf die oberste Ebene gehoben.{' '}
Berechnete Felder erscheinen in beiden Maps, unter dem Namen des berechneten Felds als
Schlüssel (answers.total).
Eine „Termin planen"-Frage und ein Zahlungsfeld tragen jeweils ein Objekt in answers, unter dem Feld-Schlüssel der Frage, und
eine Textzeile in display. Die Zeiten sind ISO-Zeitpunkte, sodass eine Tabellenkalkulation oder ein Workflow sie auswerten
kann, egal in welcher Sprache die ausfüllende Person geantwortet hat:
Der status einer Buchung ist confirmed, rescheduled, cancelled, rejected{' '}
oder no_show. Der einer Zahlung ist paid, partially_refunded, refunded oder{' '}
disputed, und amount steht in der Haupteinheit der Währung: 40 sind $40.00. Verschiebt Cal.com nach
dem Absenden eine Buchung oder erstattet Stripe eine Zahlung, aktualisiert Formstep das Objekt, sodass submissions.list und
spätere Ereignisse den aktuellen Stand zeigen; für die Änderung wird kein neues Ereignis gesendet.
Vor apiVersion 2026-09-24 wurde eine Buchung als ein einziger Satz in answers gesendet und eine
Zahlung gar nicht.
Die Feldzuordnung des Webhooks gilt für beide Maps zugleich: Wähle "ausgewählte" Felder aus, und die anderen werden ausgelassen; benenne
die Spalte eines Felds um, und der neue Name ist sein Schlüssel in answers und display gleichermaßen. Ein Feld,
das das Formular veröffentlichte, bevor es Feld-Schlüssel gab, geht unter seiner Element-ID hinaus; veröffentliche das Formular erneut, um
ihm einen lesbaren Schlüssel zu geben.
Das Event wiederholt Titel und Typ jedes Felds nicht. Lies sie aus fields.list, das pro data.form.snapshotId{' '}
stabil ist, sodass du die Feldliste cachen und nur neu abrufen kannst, wenn sich die Snapshot-ID ändert. Ein Empfänger, der keinen zweiten
Aufruf machen kann, kann Die Feldliste mit jedem Event senden in den Webhook-Einstellungen aktivieren; das Event trägt
dann data.schema, einen Eintrag pro Feld. Eine Auswahlfrage listet ihre options auf und eine Matrix ihre{' '}
rows und columns, jeweils als {'{ key, label }'}, sodass sich die Schlüssel in answers{' '}
ohne einen zweiten Aufruf zu Labels auflösen lassen:
Beim benutzerdefinierten Webhook, der in den Formulareinstellungen konfiguriert ist, trägt eine
Einreichung, die einen Request beantwortet hat, ein zusätzliches Objekt innerhalb von{' '}
data, request. Es fehlt bei jeder Einreichung über den öffentlichen Link, daher erkennt der Empfänger daran,
welcher der beiden Kanäle es war. Ein Zapier-, Make- oder n8n-Abonnement bekommt es nie zu sehen: Request-Traffic erreicht ein Abonnement
als request.completed, das den vollständigen Request-Block trägt.
id — der Request, den diese Einreichung beantwortet hat. Übergib ihn an requests.get für das vollständige
Bild.
externalId und metadata — deine eigene Buchführung, genau so, wie du sie bei requests.create{' '}
angegeben hast. Jedes erscheint nur, wenn es gesetzt wurde.
> Ein Einreichungs-Webhook feuert bei einer Einreichung; der Request-Block nennt nur den Request, den sie beantwortet hat. Ein{' '}
> Callback feuert, wenn ein Request endet — abgeschlossen, abgelaufen oder storniert —, und trägt{' '}
> context und outcome. Ablauf und Stornierung haben keine Einreichung, also feuert dafür nie ein
> Einreichungs-Webhook. Um das Ende eines Requests ohne Callback-URL zu hören, abonniere request_completed,{' '}
> request_expired oder request_canceled über webhooks.create.
>
data.submission.pdfUrl ist ein Link zum PDF der Einreichung. Ein Formular mit einem benutzerdefinierten Webhook oder einem
Zapier-, Make- oder n8n-Abonnement behält ein PDF von jeder Einreichung, sodass dessen Events den Link enthalten. Er ist nur dann{' '}
null, wenn die Einreichung kein PDF hat.
data.submission.language ist der BCP-47-Code der Sprache, in der die ausfüllende Person das Formular eingereicht hat (bei
übersetzten Formularen). Für einsprachige Formulare ist der Wert null. Verwende dieses Feld, um nach der Sprache der
ausfüllenden Person zu verzweigen oder weiterzuleiten, ohne eine separate Abfrage durchzuführen.
Wenn du submission_abandoned abonnierst, prüft Formstep stündlich auf inaktive Entwürfe. Wenn ein Entwurf länger als das
konfigurierte Inaktivitätsfenster nicht bearbeitet wurde, löst Formstep eine Zustellung aus.
Native API-Integrationen müssen idleWindow an webhooks.create senden. Zulässige Werte sind 12h,{' '}
1d, 3d und 1w. Es gibt keinen impliziten Standard; ein Abonnement für abgebrochene Einreichungen
ohne Wert wird abgelehnt.
Die Payload-Struktur ist identisch mit einer abgeschlossenen Einreichung. Zwei Unterschiede:
answers und display.
submittedAt
{' '}
— fällt auf den Zustellungszeitstempel zurück, da der Ausfüller nie offiziell eingereicht hat.
Jede Integration wird höchstens einmal pro abgebrochenem Entwurf ausgelöst. Nach der Zustellung wird der Entwurf von zukünftigen Prüfungen ausgeschlossen.
Jeder Webhook hat sein eigenes Signing-Secret — in der Oberfläche eingerichtet, wenn du einen benutzerdefinierten Webhook konfigurierst,
oder über den optionalen Parameter signingSecret (32–255 Zeichen) bei webhooks.create. Es ist nicht dasselbe wie
das Request-Signaturgeheimnis des Arbeitsbereichs, das für Request-Callbacks verwendet wird, aber
Header und Algorithmus sind identisch, sodass ein einziger Verifizierer für beide funktioniert.
Jede signierte Zustellung trägt X-Formstep-Signature: t={seconds},sha256={hex}. Der Digest ist ein
HMAC-SHA256 von {t}.{raw body}, mit deinem Secret als Schlüssel. Zwei Regeln: hashe den{' '}
rohen Body vor jeglichem Parsen oder erneuten Serialisieren, und vergleiche in konstanter Zeit.
Formstep erzwingt kein Replay-Fenster, die Toleranz oben liegt also bei dir. Eine Änderung des Secrets wirkt sich auf den nächsten Versuch aus, auch auf bereits laufende Wiederholungen — aktualisiere zuerst deinen Empfänger.
> ⚠️ **In der Produktion immer verifizieren** >Ohne Verifizierung kann jeder, der deine URL entdeckt, gefälschte Einreichungen senden.
Formstep unternimmt bis zu 5 Versuche pro Zustellung — 1 erster Versuch und 4 Wiederholungen — mit mindestens 1, 2, 4 und 8 Minuten
Abstand. Formstep sucht alle 30 Minuten nach fälligen Wiederholungen, sodass eine Wiederholung bis zu einer halben Stunde nach Ablauf
ihres Backoffs kommen kann und der letzte Versuch etwa zwei Stunden nach dem ersten erfolgt. Ein Retry-After-Header in deiner
Antwort wird respektiert, wenn er länger verlangt als der nächste Backoff-Schritt. Eine Zustellung gilt als fehlgeschlagen, wenn dein
Endpunkt:
Ein Fall wird nie wiederholt: ein Ziel, das blockiert, nicht auflösbar ist oder auf eine private Adresse verweist. Die URL wird unmittelbar vor jedem Versuch neu geprüft — DNS eingeschlossen —, sodass ein Host, der nicht mehr erlaubt ist, die Zustellung sofort scheitern lässt, statt das Budget aufzubrauchen.
Nach 5 aufeinanderfolgenden fehlgeschlagenen Zustellungen wird die Integration pausiert. Behebe den Endpunkt und aktiviere sie über Formulareinstellungen → Integrationen erneut; eine erfolgreiche Zustellung setzt den Zähler zurück.
Wiederholte Zustellungen desselben Ereignisses verwenden dieselbe id — dedupliziere also, indem du verarbeitete IDs
speicherst. Ein wirklich neues Ereignis — etwa wenn eine ausfüllende Person ihre Einreichung bearbeitet — kommt mit einer neuen{' '}
id und type: "submission.updated" an: beim benutzerdefinierten Webhook oder bei einem{' '}
submission_updated-Abonnement. Der createdAt ist der Zeitpunkt, zu dem das Ereignis eingereiht wurde, nicht der
des Zustellversuchs, und bleibt daher auch über Wiederholungen hinweg gleich. Um Bearbeitungen zu unterscheiden, lies{' '}
data.submission.editCount: Er zählt mit jeder Bearbeitung hoch, und data.submission.updatedAt gibt an, wann die
letzte stattgefunden hat.
Sowohl das Integrations-Einrichtungsfenster als auch das Detailpanel haben eine Schaltfläche Test senden. Sie sendet ein
Beispiel des abonnierten Ereignisses an deine URL, damit du die Verbindung überprüfen kannst, ohne auf eine echte Einreichung oder einen
echten Request warten zu müssen. Dieselben Beispiele stehen auch über die API zur Verfügung, als submissions.sample und{' '}
requests.sample.
Für die lokale Entwicklung stelle deinen Dev-Server mit einem Tunnel bereit:
``` # ngrok ngrok http 3000 # cloudflare tunnel cloudflared tunnel --url http://localhost:3000 ``` > 💡 **Lokale Entwicklung** >> Verwende die Tunnel-URL als deinen Webhook-Endpunkt und klicke dann auf „Test senden", um die Verbindung von Anfang bis Ende zu > überprüfen. >