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. - On quiz-mode forms (knowledge quiz, lead qualification, match quiz): the payload includes quiz scoring results alongside the answers.
When it does NOT fire:
- Partial submissions on incremental forms (where
completeis nottrue). - 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.
- You will never receive duplicate events for the same submission from NueForm's delivery system.
- You should design your integration to tolerate missed events.
No Automatic Retries
If your endpoint is unreachable, returns an error status code, or does not respond within the 5-second timeout window, the webhook delivery is silently dropped. NueForm does not queue or retry failed deliveries.
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
Although NueForm does not send duplicate events by design, network conditions (such as TCP retransmission) could theoretically cause your endpoint to receive the same payload more than once. Use the responseId field in the payload as an idempotency key to safely deduplicate.
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