Webhook-Ereignisse | NueForm Docs

NueForm sendet Webhook-Benachrichtigungen für bestimmte Ereignisse in deinem Konto. Jede Webhook-Anfrage enthält ein event-Feld in der JSON-Payload, das angibt, was passiert ist.

Aktuelle Ereignisse

`form.submitted`

Feuert, wenn eine befragte Person eine vollständige Antwort auf eines deiner Formulare übermittelt.

Eigenschaft	Wert
Ereignisname	`form.submitted`
Auslöser	Eine befragte Person füllt ein Formular aus und schickt es ab
Payload	Formulardetails, Response-ID, Antworten mit Zeitstempeln
Inkrementelle Formulare	Feuert nur, wenn die Response als `complete` markiert ist

Das ist das zentrale Webhook-Ereignis in NueForm. Es feuert sowohl bei Standard-Formularen (einmalige Übermittlung) als auch bei Formularen mit inkrementeller Übermittlung — aber nur, wenn die Response den Status „vollständig" erreicht.

Wann es feuert:

Bei einem Standard-Formular: unmittelbar nachdem die befragte Person auf „Absenden" klickt und die Response gespeichert wurde.
Bei einem inkrementellen Formular: erst wenn die finale Übermittlung mit complete: true gesendet wird. Zwischenspeicherungen lösen dieses Ereignis nicht aus.
Bei einem Formular im Fragebogen-Stil: wenn die befragte Person auf Absenden klickt. Die zuvor automatisch gespeicherten Antworten gehören zu einer unvollständigen Response und lösen dieses Ereignis nicht aus.
Bei Formularen im Quiz-Modus (Wissensquiz, Lead-Qualifizierung, Match-Quiz): Die Payload enthält nur die Antworten. Die Quiz-Ergebnisse werden mit der Response gespeichert — rufe sie über die Responses-API mit der responseId aus der Payload ab (siehe Quiz-Ergebnisse).

Wann es NICHT feuert:

Bei Teilübermittlungen inkrementeller Formulare (wenn complete nicht true ist).
Bei Antworten, die in einem Formular im Fragebogen-Stil automatisch gespeichert werden, bevor die befragte Person auf Absenden klickt.
Bei Änderungen an bestehenden Responses (Responses sind nach der Übermittlung unveränderlich).
Bei Formularentwürfen oder Vorschauen.
Bei Testübermittlungen aus der Vorschau des Formular-Builders.

Das vollständige Payload-Schema findest du unter Payloads.

Geplante zukünftige Ereignisse

Die folgenden Ereignisse sind für kommende Releases geplant. Sie sind noch nicht verfügbar, werden hier aber dokumentiert, damit du deine Integration von Anfang an zukunftskompatibel gestalten kannst.

Die unten aufgeführten zukünftigen Ereignisse können sich noch ändern. Sieh im Changelog nach, wann neue Ereignisse verfügbar werden.

`form.partial`

Wird feuern, wenn bei einem Formular mit aktivierter inkrementeller Übermittlung eine Teilantwort gespeichert wird. Damit kannst du Formularabbrüche nachverfolgen und Befragte kontaktieren, die angefangen, aber nicht abgeschlossen haben.

Eigenschaft	Geplanter Wert
Ereignisname	`form.partial`
Auslöser	Eine Teilantwort wird erstellt oder aktualisiert (nur inkrementelle Formulare)
Payload	Gleiche Struktur wie `form.submitted`, mit `completedAt` als `null`

`form.completed`

Wird feuern, wenn eine inkrementelle Response von „teilweise" zu „vollständig" wechselt. Der Unterschied zu form.submitted: Dieses Ereignis zeigt explizit an, dass eine zuvor unvollständige Response finalisiert wurde.

Eigenschaft	Geplanter Wert
Ereignisname	`form.completed`
Auslöser	Eine Teilantwort wird als vollständig markiert
Payload	Gleiche Struktur wie `form.submitted`, inklusive aller gesammelten Antworten

`form.published`

Wird feuern, wenn ein Formular veröffentlicht oder erneut veröffentlicht wird.

Eigenschaft	Geplanter Wert
Ereignisname	`form.published`
Auslöser	Ein Formular wird über das Dashboard oder die API veröffentlicht
Payload	Formular-ID, Titel, Slug, Versionsnummer, Veröffentlichungszeitstempel

`form.unpublished`

Wird feuern, wenn die Veröffentlichung eines Formulars zurückgezogen wird (Formular geht offline).

Eigenschaft	Geplanter Wert
Ereignisname	`form.unpublished`
Auslöser	Die Veröffentlichung eines Formulars wird über das Dashboard oder die API zurückgezogen
Payload	Formular-ID, Titel, Slug, Zeitstempel der Zurückziehung

Zustellgarantien

Zu verstehen, wie NueForm Webhook-Ereignisse zustellt, ist wichtig für zuverlässige Integrationen.

At-Most-Once-Zustellung

NueForm bietet derzeit At-most-once-Zustellsemantik. Jedes Ereignis wird genau einmal gesendet und bei Fehlschlag nicht wiederholt. Das bedeutet:

Dein Endpunkt kann gelegentlich Ereignisse verpassen, wenn er vorübergehend nicht erreichbar ist.
Eine Response wird nur einmal abgeschlossen, daher sendet NueForm ihr Ereignis höchstens einmal an jede Webhook-URL. Jede konfigurierte URL erhält allerdings ihre eigene Zustellung: Eine URL, die sowohl als Formular-Webhook als auch als globaler Webhook eingetragen ist, erhält jedes Ereignis zweimal. Und werden dieselben Antworten erneut übermittelt — etwa bei einer nach einem Netzwerkfehler wiederholten Übermittlung —, entsteht eine zweite Response mit eigener responseId und eigenem Ereignis.
Deine Integration sollte verpasste Ereignisse tolerieren können.

Keine automatischen Wiederholungen

Ist dein Endpunkt nicht erreichbar, liefert er einen Fehlerstatuscode oder antwortet er nicht innerhalb des 5-Sekunden-Timeouts, schlägt die Zustellung fehl und wird nicht wiederholt. NueForm protokolliert den fehlgeschlagenen Versuch, stellt ihn aber weder in eine Warteschlange noch sendet es ihn erneut.

Da es keine automatischen Wiederholungen gibt, empfehlen wir dringend, Webhooks durch regelmäßiges Polling der Responses-API zu ergänzen, um Ereignisse aufzufangen, die dein Endpunkt verpasst haben könnte.

Reihenfolge

Webhook-Ereignisse werden in der Reihenfolge ihres Auftretens versendet. Da sie aber parallel an mehrere URLs gehen und Netzwerkbedingungen schwanken, ist die Zustellreihenfolge nicht garantiert. Wenn deine Anwendung eine strikte Reihenfolge braucht, sortiere die Ereignisse nach Empfang anhand des submittedAt-Zeitstempels in der Payload.

Timeout

NueForm wartet bis zu 5 Sekunden auf die Antwort deines Endpunkts. Antwortet er nicht innerhalb dieses Fensters, wird die Anfrage abgebrochen. Dein Endpunkt sollte so schnell wie möglich mit einem 2xx-Statuscode antworten und aufwendige Verarbeitung in einen Hintergrund-Job auslagern.

Idempotenz

Dein Endpunkt kann dasselbe Ereignis mehrfach erhalten — zum Beispiel, wenn dieselbe URL sowohl als Formular-Webhook als auch als globaler Webhook eingetragen ist. Nutze das responseId-Feld der Payload als Idempotenzschlüssel, um sicher zu deduplizieren.

Best Practices

Antworte schnell. Gib sofort 200 OK zurück und verarbeite die Webhook-Daten asynchron. NueForm hat ein Timeout von 5 Sekunden.
Prüfe Signaturen. Validiere immer den X-NueForm-Signature-Header, bevor du der Payload vertraust. Siehe Verifizierung.
Nutze Idempotenzschlüssel. Speichere verarbeitete responseId-Werte und überspringe Duplikate.
Gleiche regelmäßig ab. Ergänze Echtzeit-Webhooks durch geplantes Polling der Responses-API, um verpasste Ereignisse aufzufangen.
Überwache deinen Endpunkt. Verfolge Antwortzeiten und Fehlerraten deines Webhook-Endpunkts. Wenn dein Endpunkt regelmäßig ausfällt, ziehe eine Queue (z. B. SQS, Redis) zwischen Webhook-Empfänger und Verarbeitungslogik in Betracht.

Nächste Schritte

Payloads --- Das vollständige JSON-Payload-Schema
Verifizierung --- Signaturprüfung implementieren
Testen --- Webhook-Zustellung lokal testen