Charges utiles Webhook

Every NueForm webhook request sends a JSON payload in the request body. This page documents the complete payload schema for each event type.

Common Structure

All webhook payloads share these top-level fields:

form.submitted Payload

This is the payload sent when a respondent submits a complete form response.

Full Example

{
  "event": "form.submitted",
  "formId": "507f1f77bcf86cd799439011",
  "formTitle": "Customer Feedback Survey",
  "responseId": "507f1f77bcf86cd799439022",
  "answers": [
    {
      "questionId": "507f1f77bcf86cd799439033",
      "value": "Jane Doe"
    },
    {
      "questionId": "507f1f77bcf86cd799439044",
      "value": "jane@example.com"
    },
    {
      "questionId": "507f1f77bcf86cd799439055",
      "value": 4
    },
    {
      "questionId": "507f1f77bcf86cd799439066",
      "value": "The onboarding flow was smooth and intuitive."
    },
    {
      "questionId": "507f1f77bcf86cd799439077",
      "value": ["Feature A", "Feature C"]
    },
    {
      "questionId": "507f1f77bcf86cd799439088",
      "value": true
    }
  ],
  "respondent": {
    "id": "507f1f77bcf86cd799439016",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "auth_method": "sso"
  },
  "submittedAt": "2025-03-15T14:32:07.123Z"
}

Field Reference

Top-Level Fields

event --- string

Always "form.submitted" for this event type.

formId --- string

The MongoDB ObjectId of the form. This is a 24-character hexadecimal string.

formTitle --- string

The human-readable title of the form at the time the webhook fires. Note that if you rename the form later, previously delivered webhooks will still contain the old title.

responseId --- string

The MongoDB ObjectId of the stored response. You can use this to fetch the full response via the Responses API or as an idempotency key to deduplicate webhook deliveries.

submittedAt --- string

ISO 8601 timestamp indicating when the webhook was dispatched. This is generated at dispatch time and will be very close to (but not necessarily identical to) the response's submittedAt field in the database.

respondent --- object or null

Identity of the logged-in user who submitted the response, surfaced only when the form required login (requireLogin: true). null for all anonymous submissions. See Respondent Identity below for the full schema and behaviour.

Answer Objects

Each entry in the answers array represents a single question's response:

Answer Values by Question Type

The value field in each answer object varies depending on the question type. Here is the format for each type:

Text Inputs

Choice Questions

Rating Questions

Date and Time

The date string format matches the dateFormat property configured on the question (defaults to YYYY-MM-DD).

Legal and Statements

Ranking

The array reflects the respondent's chosen order, from first to last.

Matrix

The object maps row labels to the selected column label for each row.

File Upload

The value is the URL of the uploaded file in NueForm's storage.

Signature and Drawing

Both return a base64-encoded PNG data URI of the captured image.

Recording

The value is the URL of the uploaded recording file.

Composite Questions

Composite question types (contact_info, address, question_group, multi_question_page) produce multiple answer entries in the answers array --- one for each sub-field. Each sub-field answer uses the sub-field's own questionId.

For example, a contact_info question might produce:

[
  { "questionId": "first_name", "value": "Jane" },
  { "questionId": "last_name", "value": "Doe" },
  { "questionId": "email", "value": "jane@example.com" },
  { "questionId": "phone_number", "value": "+1 555-0100" },
  { "questionId": "company", "value": "Acme Inc." }
]

Respondent Identity

When a form is configured with requireLogin: true, every accepted submission is tied to a signed-in user. Webhook payloads expose that identity to form owners through the respondent field. For all other submissions the field is null.

Schema

{
  "respondent": {
    "id": "507f1f77bcf86cd799439016",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "auth_method": "sso"
  }
}

When respondent is populated

respondent is populated only when:

1. The form has requireLogin set to true, and
2. The submitter signed in because the form required it before submitting.

When requireSsoLogin is also true, only users who are members of the form's team via SSO can reach the submit step, so every populated respondent will have auth_method: "sso".

When respondent is null

The field is always present in the JSON for predictable downstream parsing, and is null whenever any of these is true:

• The form did not require login (requireLogin was false).
• The submitter was anonymous.
• The response was saved via the post-submit consent flow (the "claim this response" prompt). Consent-saved responses never appear in webhook payloads with identity attached — they are stored only in the user's "My Responses" view and are not exposed to webhook receivers.

Quiz Results

For forms running in a quiz mode (knowledge_quiz, lead_qualification, or match_quiz), the stored response includes a quizResults object. While this object is not directly included in the webhook payload, you can retrieve it via the Responses API using the responseId from the webhook.

The quizResults object has the following structure:

{
  "formMode": "knowledge_quiz",
  "score": 7,
  "correctAnswers": 7,
  "totalScorableQuestions": 10,
  "maxScore": 10,
  "matchedEndingId": "507f1f77bcf86cd799439099"
}

Metadata

The stored response may also include a metadata object containing hidden fields passed via URL parameters. This is available via the Responses API but is not included in the webhook payload.

{
  "hiddenFields": {
    "utm_source": "google",
    "utm_campaign": "spring_sale",
    "user_id": "ext_12345"
  }
}

To access metadata for a webhook-delivered response, fetch it using the responseId:

curl https://app.nueform.com/api/v1/forms/FORM_ID/responses/RESPONSE_ID \
  -H "Authorization: Bearer nf_your_api_key"

HTTP Headers

Every webhook request includes these HTTP headers:

See Verification for how to validate the signature.

Payload Size

Webhook payloads are typically small (under 10 KB). The size depends primarily on the number of questions and the length of text answers. File upload answers contain URLs (not file contents), so they do not significantly increase payload size.

Next Steps

• Verification --- Validate webhook signatures
• Testing --- Test webhook payloads locally
• Events --- Event types and delivery guarantees