NueForm आपके account में होने वाले specific events के लिए webhook notifications भेजता है। प्रत्येक webhook request में JSON payload में event field शामिल होता है जो identify करता है कि क्या हुआ।
Current Events
form.submitted
जब respondent आपके किसी form पर complete response submit करता है तब fire होता है।
| Property | Value |
|---|---|
| Event name | form.submitted |
| Trigger | Respondent form response complete और submit करता है |
| Payload | Form details, response ID, timestamped answers |
| Incremental forms | केवल तब fire होता है जब response complete के रूप में mark होता है |
यह NueForm में primary webhook event है। यह standard (single-submit) forms और incremental submission forms दोनों के लिए fire होता है, लेकिन केवल तब जब response completed state तक पहुंचता है।
कब fire होता है:
- Standard form पर: respondent Submit click करने और response save होने के तुरंत बाद।
- Incremental form पर: केवल तब जब final submission
complete: trueके साथ भेजी जाती है। Partial saves इस event को trigger नहीं करते। - Quiz-mode forms (knowledge quiz, lead qualification, match quiz) पर: payload में answers के साथ quiz scoring results भी शामिल होते हैं।
कब fire नहीं होता:
- Incremental forms पर partial submissions (जहां
completetrueनहीं है)। - Existing responses में edits (responses submit होने के बाद immutable हैं)।
- Form drafts या previews।
- Form builder preview से test submissions।
Full payload schema के लिए Payloads देखें।
Planned Future Events
निम्नलिखित events future releases के लिए planned हैं। ये अभी उपलब्ध नहीं हैं लेकिन यहां documented हैं ताकि आप forward compatibility को ध्यान में रखकर अपना integration design कर सकें।
नीचे listed future events बदलाव के अधीन हैं। नए events उपलब्ध होने पर announcements के लिए Changelog check करें।
form.partial
Incremental submission enabled form पर partial response save होने पर fire होगा। इससे आप form abandonment track कर सकेंगे और उन respondents को follow up कर सकेंगे जिन्होंने शुरू किया लेकिन finish नहीं किया।
| Property | Planned Value |
|---|---|
| Event name | form.partial |
| Trigger | Partial response create या update होता है (केवल incremental forms) |
| Payload | form.submitted जैसी ही structure null completedAt के साथ |
form.completed
Incremental response partial से complete में transition होने पर fire होगा। यह form.submitted से इस मायने में different है कि यह explicitly indicate करता है कि पहले से partial response finalize हो गया है।
| Property | Planned Value |
|---|---|
| Event name | form.completed |
| Trigger | Partial response complete के रूप में mark होता है |
| Payload | form.submitted जैसी ही structure, सभी accumulated answers सहित |
form.published
Form publish या republish होने पर fire होगा।
| Property | Planned Value |
|---|---|
| Event name | form.published |
| Trigger | Dashboard या API के माध्यम से form publish होता है |
| Payload | Form ID, title, slug, version number, published timestamp |
form.unpublished
Form unpublish (offline) होने पर fire होगा।
| Property | Planned Value |
|---|---|
| Event name | form.unpublished |
| Trigger | Dashboard या API के माध्यम से form unpublish होता है |
| Payload | Form ID, title, slug, unpublished timestamp |
Event Delivery Guarantees
NueForm webhook events कैसे deliver करता है यह समझना reliable integrations build करने के लिए महत्वपूर्ण है।
At-Most-Once Delivery
NueForm वर्तमान में at-most-once delivery semantics provide करता है। प्रत्येक event एक बार भेजा जाता है और delivery fail होने पर retry नहीं होता। इसका मतलब है:
- यदि आपका endpoint temporarily unavailable है तो आपका endpoint occasionally events miss कर सकता है।
- आपको NueForm के delivery system से same submission के लिए कभी duplicate events receive नहीं होंगे।
- आपको अपना integration missed events tolerate करने के लिए design करना चाहिए।
कोई Automatic Retries नहीं
यदि आपका endpoint unreachable है, error status code return करता है, या 5-second timeout window के भीतर respond नहीं करता, webhook delivery silently drop हो जाती है। NueForm failed deliveries queue या retry नहीं करता।
चूंकि कोई automatic retries नहीं हैं, हम strongly recommend करते हैं कि webhooks को Responses API की periodic polling से supplement करें ताकि आपके endpoint द्वारा miss किए गए events catch हो सकें।
Ordering
Webhook events होने के order में dispatch होते हैं, लेकिन चूंकि ये multiple URLs पर parallel में भेजे जाते हैं और network conditions vary करती हैं, delivery order guaranteed नहीं है। यदि आपके application को strict ordering की आवश्यकता है, receipt के बाद events sort करने के लिए payload में submittedAt timestamp उपयोग करें।
Timeout
NueForm आपके endpoint के respond करने के लिए 5 seconds तक wait करता है। यदि आपका endpoint इस window के भीतर respond नहीं करता, request abort हो जाती है। आपका endpoint जल्द से जल्द 2xx status code respond करे और किसी भी heavy processing को background job में defer करे।
Idempotency
हालांकि NueForm design से duplicate events नहीं भेजता, network conditions (जैसे TCP retransmission) theoretically आपके endpoint को same payload एक से अधिक बार receive करा सकती हैं। Safely deduplicate करने के लिए payload में responseId field को idempotency key के रूप में उपयोग करें।
Best Practices
जल्दी respond करें। तुरंत
200 OKreturn करें और webhook data asynchronously process करें। NueForm का 5-second timeout है।Signatures verify करें। Payload पर trust करने से पहले हमेशा
X-NueForm-Signatureheader validate करें। Verification देखें।Idempotency keys उपयोग करें। Processed
responseIdvalues store करें और duplicates skip करें।Periodically reconcile करें। Missed events catch करने के लिए real-time webhooks को Responses API की scheduled polling से supplement करें।
अपने endpoint की monitoring करें। अपने webhook endpoint पर response times और error rates track करें। यदि आपका endpoint consistently fail होता है, अपने webhook receiver और processing logic के बीच queue (जैसे, SQS, Redis) implement करने पर विचार करें।
Next Steps
- Payloads --- पूर्ण JSON payload schema देखें
- Verification --- Signature verification implement करें
- Testing --- Locally webhook delivery test करें