NueForm sends webhook notifications for specific events that occur within your account. Each webhook request includes an event field in the JSON payload that identifies what happened.
Current Events
form.submitted
Fires when a respondent submits a complete response to one of your forms.
| Property | Value |
|---|---|
| Event name | form.submitted |
| Trigger | A respondent completes and submits a form response |
| Payload | Form details, response ID, timestamped answers |
| Incremental forms | Only fires when the response is marked as complete |
This is the primary webhook event in NueForm. It fires for both standard (single-submit) forms and incremental submission forms, but only when the response reaches a completed state.
When it fires:
- On a standard form: immediately after the respondent clicks Submit and the response is saved.
- On an incremental form: only when the final submission is sent with
complete: true. Partial saves do not trigger this event. - Sur un formulaire de style Questionnaire : lorsque le répondant clique sur Soumettre. Les réponses enregistrées automatiquement avant ce moment appartiennent à une réponse inachevée et ne déclenchent pas cet événement.
- Sur les formulaires en mode quiz (knowledge quiz, lead qualification, match quiz) : le payload ne contient que les réponses. Les résultats du quiz sont stockés avec la réponse — récupérez-les via l'API des réponses à l'aide du
responseIddu payload (voir Résultats de quiz).
When it does NOT fire:
- Partial submissions on incremental forms (where
completeis nottrue). - Les réponses enregistrées automatiquement sur un formulaire de style Questionnaire avant que le répondant ne clique sur Soumettre.
- Edits to existing responses (responses are immutable once submitted).
- Form drafts or previews.
- Test submissions from the form builder preview.
See Payloads for the full payload schema.
Planned Future Events
The following events are planned for future releases. They are not yet available but are documented here so you can design your integration with forward compatibility in mind.
Future events listed below are subject to change. Check the Changelog for announcements when new events become available.
form.partial
Will fire when a partial response is saved on a form with incremental submission enabled. This will allow you to track form abandonment and follow up with respondents who started but did not finish.
| Property | Planned Value |
|---|---|
| Event name | form.partial |
| Trigger | A partial response is created or updated (incremental forms only) |
| Payload | Same structure as form.submitted with a null completedAt |
form.completed
Will fire when an incremental response transitions from partial to complete. This differs from form.submitted in that it explicitly indicates a previously partial response has been finalized.
| Property | Planned Value |
|---|---|
| Event name | form.completed |
| Trigger | A partial response is marked as complete |
| Payload | Same structure as form.submitted, including all accumulated answers |
form.published
Will fire when a form is published or republished.
| Property | Planned Value |
|---|---|
| Event name | form.published |
| Trigger | A form is published via the dashboard or API |
| Payload | Form ID, title, slug, version number, published timestamp |
form.unpublished
Will fire when a form is unpublished (taken offline).
| Property | Planned Value |
|---|---|
| Event name | form.unpublished |
| Trigger | A form is unpublished via the dashboard or API |
| Payload | Form ID, title, slug, unpublished timestamp |
Event Delivery Guarantees
Understanding how NueForm delivers webhook events is important for building reliable integrations.
At-Most-Once Delivery
NueForm currently provides at-most-once delivery semantics. Each event is sent once and is not retried if delivery fails. This means:
- Your endpoint may occasionally miss events if it is temporarily unavailable.
- Une réponse n'est finalisée qu'une seule fois : NueForm envoie donc son événement au plus une fois à chaque URL de webhook. Chaque URL configurée reçoit toutefois sa propre livraison : une URL définie à la fois comme webhook du formulaire et comme webhook global reçoit chaque événement deux fois. Et si les mêmes réponses sont soumises à nouveau — par exemple, une soumission relancée après une erreur réseau —, une seconde réponse est créée, avec son propre
responseIdet son propre événement. - You should design your integration to tolerate missed events.
No Automatic Retries
Si votre endpoint est injoignable, renvoie un code d'erreur ou ne répond pas dans le délai de 5 secondes, la livraison échoue et n'est pas relancée. NueForm enregistre la tentative échouée, mais ne la met pas en file d'attente et ne la renvoie pas.
Because there are no automatic retries, we strongly recommend supplementing webhooks with periodic polling of the Responses API to catch any events your endpoint may have missed.
Ordering
Webhook events are dispatched in the order they occur, but because they are sent to multiple URLs in parallel and network conditions vary, delivery order is not guaranteed. If your application requires strict ordering, use the submittedAt timestamp in the payload to sort events after receipt.
Timeout
NueForm waits up to 5 seconds for your endpoint to respond. If your endpoint does not respond within this window, the request is aborted. Your endpoint should respond with a 2xx status code as quickly as possible and defer any heavy processing to a background job.
Idempotency
Votre endpoint peut recevoir le même événement plusieurs fois — par exemple, lorsque la même URL est configurée à la fois comme webhook du formulaire et comme webhook global. Utilisez le champ responseId du payload comme clé d'idempotence pour dédupliquer en toute sécurité.
Meilleures pratiques
Respond quickly. Return a
200 OKimmediately and process the webhook data asynchronously. NueForm has a 5-second timeout.Verify signatures. Always validate the
X-NueForm-Signatureheader before trusting the payload. See Verification.Use idempotency keys. Store processed
responseIdvalues and skip duplicates.Reconcile periodically. Supplement real-time webhooks with scheduled polling of the Responses API to catch any missed events.
Monitor your endpoint. Track response times and error rates on your webhook endpoint. If your endpoint consistently fails, consider implementing a queue (e.g., SQS, Redis) between your webhook receiver and your processing logic.
Next Steps
- Payloads --- See the full JSON payload schema
- Verification --- Implement signature verification
- Testing --- Test webhook delivery locally