Webhook Payloads | NueForm Docs

प्रत्येक NueForm webhook request body में JSON payload भेजता है। यह page प्रत्येक event type के लिए पूर्ण payload schema document करता है।

Common Structure

सभी webhook payloads ये top-level fields share करते हैं:

Field	Type	विवरण
`event`	`string`	Event type (जैसे, `form.submitted`)
`formId`	`string`	Form की unique ID
`formTitle`	`string`	Submission के समय form का title
`responseId`	`string`	Response की unique ID
`answers`	`array`	Answer objects का array
`submittedAt`	`string`	Event dispatch होने का ISO 8601 timestamp

`form.submitted` Payload

जब respondent complete form response submit करता है तब यह payload भेजा जाता है।

Full Example

json

{
  "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
    }
  ],
  "submittedAt": "2025-03-15T14:32:07.123Z"
}

Field Reference

Top-Level Fields

event --- string

इस event type के लिए हमेशा "form.submitted"।

formId --- string

Form की MongoDB ObjectId। यह 24-character hexadecimal string है।

formTitle --- string

Webhook fire होने के समय form का human-readable title। ध्यान दें कि यदि आप बाद में form rename करते हैं, पहले delivered webhooks में अभी भी पुराना title होगा।

responseId --- string

Stored response की MongoDB ObjectId। आप इसे Responses API के माध्यम से full response fetch करने या webhook deliveries deduplicate करने के लिए idempotency key के रूप में उपयोग कर सकते हैं।

submittedAt --- string

Webhook dispatch होने का ISO 8601 timestamp। यह dispatch time पर generate होता है और database में response के submittedAt field के बहुत करीब (लेकिन necessarily identical नहीं) होगा।

Answer Objects

answers array में प्रत्येक entry एक single question का response represent करती है:

Field	Type	विवरण
`questionId`	`string`	Question की MongoDB ObjectId
`value`	`any`	Respondent का answer (format question type पर निर्भर)

Question Type के अनुसार Answer Values

प्रत्येक answer object में value field question type पर निर्भर करता है। यहां प्रत्येक type के लिए format है:

Text Inputs

Question Type	Value Type	Example
`short_text`	`string`	`"Jane Doe"`
`long_text`	`string`	`"I really enjoyed the product..."`
`email`	`string`	`"jane@example.com"`
`phone`	`string`	`"+1 (555) 123-4567"`
`number`	`number`	`42`
`url`	`string`	`"https://example.com"`

Choice Questions

Question Type	Value Type	Example
`multiple_choice` (single)	`string`	`"Option A"`
`multiple_choice` (multi)	`array<string>`	`["Option A", "Option C"]`
`dropdown`	`string`	`"United States"`
`yes_no`	`boolean`	`true`
`picture_choice` (single)	`string`	`"choice_id_abc123"`
`picture_choice` (multi)	`array<string>`	`["choice_id_abc123", "choice_id_def456"]`

multiple_choice questions के लिए, allowMultiple false होने पर value single string होती है, और allowMultiple true होने पर strings का array। यदि respondent "Other" option select करता है, array में उनकी free-text entry string के रूप में शामिल होगी।

Rating Questions

Question Type	Value Type	Example	Range
`rating`	`number`	`4`	1 से `steps` (default 5)
`opinion_scale`	`number`	`7`	`min` से `max`
`nps`	`number`	`9`	0 से 10

Date और Time

Question Type	Value Type	Example
`date`	`string`	`"2025-03-15"`

Date string format question पर configured dateFormat property से match करता है (default YYYY-MM-DD)।

Legal और Statements

Question Type	Value Type	Example
`legal`	`boolean`	`true`
`statement`	`string`	`""` (हमेशा empty --- statements कोई data collect नहीं करते)

Ranking

Question Type	Value Type	Example
`ranking`	`array<string>`	`["Speed", "Price", "Quality"]`

Array respondent के chosen order को reflect करता है, first से last तक।

Matrix

Question Type	Value Type	Example
`matrix`	`object`	`{ "Speed": "Satisfied", "Price": "Neutral" }`

Object row labels को प्रत्येक row के लिए selected column label से map करता है।

File Upload

Question Type	Value Type	Example
`file_upload`	`string`	`"https://storage.nueform.com/uploads/abc123.pdf"`

Value NueForm के storage में uploaded file का URL है।

Signature और Drawing

Question Type	Value Type	Example
`signature`	`string`	`"data:image/png;base64,iVBOR..."`
`drawing`	`string`	`"data:image/png;base64,iVBOR..."`

दोनों captured image की base64-encoded PNG data URI return करते हैं।

Recording

Question Type	Value Type	Example
`recording`	`string`	`"https://storage.nueform.com/recordings/abc123.webm"`

Value uploaded recording file का URL है।

Composite Questions

Composite question types (contact_info, address, question_group, multi_question_page) answers array में multiple answer entries produce करते हैं --- प्रत्येक sub-field के लिए एक। प्रत्येक sub-field answer sub-field की अपनी questionId उपयोग करता है।

उदाहरण के लिए, एक contact_info question produce कर सकता है:

json

[
  { "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." }
]

Quiz Results

Quiz mode (knowledge_quiz, lead_qualification, या match_quiz) में चलने वाले forms के लिए, stored response में quizResults object शामिल होता है। हालांकि यह object webhook payload में directly शामिल नहीं है, आप इसे webhook से responseId उपयोग करके Responses API के माध्यम से retrieve कर सकते हैं।

quizResults object की निम्नलिखित structure है:

json

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

Field	Type	विवरण
`formMode`	`string`	Quiz mode: `knowledge_quiz`, `lead_qualification`, या `match_quiz`
`score`	`number`	Respondent का total score
`correctAnswers`	`number`	Correctly answer किए गए questions की संख्या (केवल knowledge quiz; अन्य modes के लिए `0`)
`totalScorableQuestions`	`number`	Score में contribute करने वाले questions की कुल संख्या
`maxScore`	`number`	Maximum achievable score
`matchedEndingId`	`string` या `undefined`	Respondent के score के आधार पर दिखाई गई end screen की ID
`endingTallies`	`object` या `undefined`	केवल Match quiz: प्रत्येक end screen ID को उसकी tally count से map करता है

Metadata

Stored response में URL parameters के माध्यम से pass किए गए hidden fields युक्त metadata object भी शामिल हो सकता है। यह Responses API के माध्यम से उपलब्ध है लेकिन webhook payload में शामिल नहीं है।

json

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

Webhook-delivered response के लिए metadata access करने के लिए, responseId उपयोग करके fetch करें:

bash

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

HTTP Headers

प्रत्येक webhook request में ये HTTP headers शामिल होते हैं:

Header	Value
`Content-Type`	`application/json`
`X-NueForm-Signature`	Raw request body का HMAC-SHA256 hex digest

Signature validate करने के तरीके के लिए Verification देखें।

Payload Size

Webhook payloads typically small (10 KB से कम) होते हैं। Size मुख्य रूप से questions की संख्या और text answers की length पर निर्भर करता है। File upload answers में URLs (file contents नहीं) होते हैं, इसलिए वे payload size significantly नहीं बढ़ाते।

Next Steps

Verification --- Webhook signatures validate करें
Testing --- Locally webhook payloads test करें
Events --- Event types और delivery guarantees