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",
      "label": "What's your name?",
      "type": "short_text"
    },
    {
      "questionId": "507f1f77bcf86cd799439044",
      "value": "jane@example.com",
      "label": "What's your email address?",
      "type": "email"
    },
    {
      "questionId": "507f1f77bcf86cd799439055",
      "value": 4,
      "label": "How would you rate your experience?",
      "type": "rating"
    },
    {
      "questionId": "507f1f77bcf86cd799439066",
      "value": "The onboarding flow was smooth and intuitive.",
      "label": "What did you like most?",
      "type": "long_text"
    },
    {
      "questionId": "507f1f77bcf86cd799439077",
      "value": ["c3a1e5f2-8b4d-4f6a-9e21-7d0b3c8a5f14", "9b7e2d41-5c3f-4a8e-b6d0-1f2a4c6e8b93"],
      "label": "Which features do you use?",
      "type": "multiple_choice"
    },
    {
      "questionId": "507f1f77bcf86cd799439088",
      "value": true,
      "label": "Would you recommend us?",
      "type": "yes_no"
    }
  ],
  "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:

Les réponses issues d'appels téléphoniques contiennent questionId, value et, pour une liste tirée d'une variable, valueLabels. Les réponses web peuvent aussi contenir viewedAt et answeredAt : le moment où la question a été affichée et celui où elle a reçu une réponse, sous forme d'horodatages ISO 8601 issus de l'appareil du répondant. D'autres champs pourront s'ajouter avec le temps : ignorez ceux dont vous ne vous servez pas.

Une réponse web à une liste chargée depuis une variable ressemble à ceci :

{
  "questionId": "507f1f77bcf86cd799439099",
  "value": "siamese",
  "label": "Which breed is your cat?",
  "type": "dropdown",
  "valueLabels": { "siamese": "Siamese" }
}

La même réponse donnée lors d'un appel téléphonique arrive sans label ni type.

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

value contient des ID de choix, pas des libellés : l'id de chaque choix sélectionné dans les choices de la question. L'éditeur crée ces ID sous forme d'UUID. L'API et le serveur MCP acceptent aussi un choix sans id, comme { "label": "Search engine" } ; dans une réponse web, value contient alors le label de ce choix au lieu d'un ID. multiple_choice et dropdown envoient une seule chaîne, ou un tableau de chaînes quand allowMultiple vaut true. Les choix avec image (layout: "blocks") sont aussi des questions multiple_choice.

Si le répondant choisit Autre, l'entrée est __other__: suivi du texte qu'il a saisi, comme dans l'exemple ci-dessus. Un appel téléphonique enregistre une réponse Autre avec les propres mots de l'appelant, sans le préfixe.

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

Le tableau contient des ID de choix dans l'ordre du répondant, du premier au dernier ; dans une réponse web, un choix enregistré sans id y figure par son label au lieu d'un ID. Associez les ID à leurs libellés comme pour les questions à choix.

Matrix

Pour une Matrice aux lignes et colonnes fixes, l'objet associe le libellé de chaque ligne au libellé de la colonne choisie. Quand ses lignes ou ses colonnes viennent d'une variable, il associe des valeurs de ligne à des valeurs de colonne, et les libellés vus par le répondant se trouvent dans le valueLabels de la réponse, sous les clés row:<valeur> et column:<valeur>.

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

Les types de questions composites (contact_info, address, question_group, multi_question_page) produisent une seule entrée de réponse, sous le questionId de la question composite elle-même. Son value est un objet dont les clés sont les ID des sous-champs. Coordonnées et Adresse utilisent des ID intégrés comme first_name et zip_code ; pour un Groupe de questions ou une Page multi-questions, ce sont les ID des questions qu'ils contiennent. La valeur de chaque sous-champ suit le format de son propre type de question. Les réponses web contiennent aussi subLabels, qui associe l'ID de chaque sous-champ à son libellé.

Par exemple, une question contact_info produit :

{
  "questionId": "507f1f77bcf86cd7994390aa",
  "value": {
    "first_name": "Jane",
    "last_name": "Doe",
    "phone_number": "+1 555-0100",
    "email": "jane@example.com",
    "company": "Acme Inc."
  },
  "label": "How can we reach you?",
  "type": "contact_info",
  "subLabels": {
    "first_name": "First Name",
    "last_name": "Last Name",
    "phone_number": "Phone Number",
    "email": "Email",
    "company": "Company"
  }
}

La même réponse donnée lors d'un appel téléphonique a le même value, sans label, type ni subLabels.

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.io/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