Webhook Payloads

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

Common Structure

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

form.submitted Payload

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

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

इस 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 नहीं) होगा।

respondent --- object या null

Logged-in user की identity जिसने response submit की, केवल तब expose होती है जब form ने login require किया था (requireLogin: true)। सभी anonymous submissions के लिए null। पूर्ण schema और behaviour के लिए नीचे Respondent Identity देखें।

Answer Objects

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

Phone calls से आए answers में questionId, value और, variable से ली गई list के लिए, valueLabels होते हैं। Web answers में viewedAt और answeredAt भी हो सकते हैं — question कब दिखाया गया और कब उसका जवाब दिया गया, respondent के device के ISO 8601 timestamps के रूप में। समय के साथ और fields जुड़ सकते हैं, इसलिए जिन fields का आप उपयोग नहीं करते उन्हें ignore करें।

Variable से load हुई list का web answer ऐसा दिखता है:

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

Phone call पर दिया गया वही answer label और type के बिना आता है।

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

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

Text Inputs

Choice Questions

value में choice IDs होती हैं, labels नहीं: question की choices में हर चुनी गई choice का id। Builder ये IDs UUID के रूप में बनाता है। API और MCP server बिना id वाली choice भी स्वीकार करते हैं, जैसे { "label": "Search engine" }; तब web answer के value में ID की जगह उस choice का label होता है। multiple_choice और dropdown एक single string भेजते हैं, या allowMultiple true होने पर strings का array। Image choices (layout: "blocks") भी multiple_choice questions ही हैं।

अगर respondent अन्य चुनता है, तो entry __other__: और उसके बाद respondent का लिखा text होती है, जैसा ऊपर के example में है। Phone call पर "अन्य" answer caller के अपने शब्दों में, बिना prefix के save होता है।

Rating Questions

Date और Time

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

Legal और Statements

Ranking

Array में choice IDs respondent के चुने हुए order में होती हैं, first से last तक; web answer में, बिना id के save की गई choice ID की जगह अपने label के रूप में आती है। Labels से IDs को वैसे ही match करें जैसे Choice Questions में।

Matrix

Fixed rows और columns वाले Matrix में object हर row label को selected column label से map करता है। जब rows या columns किसी variable से आती हैं, तो यह row values को column values से map करता है, और respondent के देखे labels answer के valueLabels में row:<value> और column:<value> keys के नीचे होते हैं।

File Upload

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

Signature और Drawing

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

Recording

Value uploaded recording file का URL है।

Composite Questions

Composite question types (contact_info, address, question_group, multi_question_page) एक ही answer entry produce करते हैं, composite question की अपनी questionId के साथ। उसका value एक object है, जिसकी keys sub-field IDs होती हैं। संपर्क जानकारी और पता first_name और zip_code जैसी built-in IDs उपयोग करते हैं; प्रश्न समूह या बहु-प्रश्न पृष्ठ अपने अंदर के हर question की ID उपयोग करता है। हर sub-field की value उसके अपने question type के format में होती है। Web answers में subLabels भी होता है, जो हर sub-field की ID को उसके label से जोड़ता है।

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

{
  "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"
  }
}

Phone call पर दिया गया वही answer उसी value के साथ, लेकिन label, type और subLabels के बिना आता है।

Respondent Identity

जब एक form requireLogin: true के साथ configured होता है, तो हर accepted submission एक signed-in user से tied होता है। Webhook payloads form owners को respondent field के माध्यम से उस identity को expose करते हैं। अन्य सभी submissions के लिए field null होती है।

Schema

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

respondent कब populated होता है

respondent केवल तब populate होता है जब:

1. Form में requireLogin true set है, और
2. Submitter ने submit करने से पहले sign in किया क्योंकि form ने require किया था।

जब requireSsoLogin भी true है, केवल वे users जो SSO के माध्यम से form की team के members हैं, submit step तक पहुँच सकते हैं, इसलिए हर populated respondent का auth_method: "sso" होगा।

respondent कब null होता है

Predictable downstream parsing के लिए field हमेशा JSON में present है, और इन में से कोई भी true होने पर null है:

• Form ने login require नहीं किया था (requireLogin false था)।
• Submitter anonymous था।
• Response को post-submit consent flow ("इस response को claim करें" prompt) के माध्यम से save किया गया था। Consent-saved responses कभी भी identity attached के साथ webhook payloads में नहीं दिखाई देते — वे केवल user के "My Responses" view में store होते हैं और webhook receivers को expose नहीं किए जाते।

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 है:

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

Metadata

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

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

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

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

HTTP Headers

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

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