Skip to main content
ThunderPhone आपके सर्वर को HTTP POST अनुरोध भेजता है जब कॉल के दौरान घटनाएं होती हैं — इनबाउंड कॉल शुरू होती है, कॉल समाप्त होती है, ग्रेडिंग रन पूरा होता है, अलर्ट ट्रिगर होता है, आदि। दो डिलीवरी मॉडल हैं:

Webhook एंडपॉइंट्स (अनुशंसित)

कई URL, प्रति-एंडपॉइंट सीक्रेट्स, प्रति-एंडपॉइंट इवेंट फ़िल्टर, और ऑटोमैटिक रिट्राइ। GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints के माध्यम से प्रबंधित करें।

सिंगल-URL लेगसी webhook

प्रति संगठन एक URL। इसमें ब्लॉकिंग कॉन्फ़िगरेशन एक्सचेंज सहित कॉल-लाइफसाइकल इवेंट शामिल होते हैं। GET/PUT /v1/webhook पर प्रबंधित किया जाता है।
इवेंट्स कैटलॉग के सभी दस इवेंट प्रकार webhook एंडपॉइंट्स के माध्यम से डिलीवर किए जाते हैं। छह कॉल-लाइफसाइकल इवेंट (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) भी लेगसी सिंगल-URL webhook को भेजे जाते हैं — यदि आपके पास लेगसी URL और एक मैचिंग एंडपॉइंट दोनों हैं, तो आपको इवेंट दोनों पाथ पर प्राप्त होता है। ब्लॉकिंग व्यवहार ( telephony.incoming / web.incoming कॉन्फ़िगरेशन एक्सचेंज और webhook-मोड टूल डिस्पैच) केवल लेगसी पाथ पर उपलब्ध है; प्रत्येक एंडपॉइंट डिलीवरी एक fire-and-forget नोटिफ़िकेशन है।

Payload फ़ॉर्मैट

एंडपॉइंट डिलीवरी data, event_id, और type वाला एक JSON ऑब्जेक्ट होती है:
event_id प्रत्येक उत्सर्जित इवेंट के लिए यूनिक है। यह रिट्राइ के दौरान और इवेंट प्राप्त करने वाले हर एंडपॉइंट पर समान रहता है — इसके आधार पर डीडुप्लिकेट करें। लेगसी सिंगल-URL webhook समान type और data भेजता है, लेकिन event_id के बिना:
वायर पर, हर बॉडी कैनॉनिकली सीरियलाइज़ होती है — कीज़ को वर्णानुक्रम में सॉर्ट किया जाता है, कोई व्हाइटस्पेस नहीं होता, और UTF-8 का उपयोग होता है। इन डॉक्यूमेंट्स में प्रिटी-प्रिंट किए गए उदाहरण केवल पठनीयता के लिए हैं। इवेंट प्रकारों और payload फ़ील्ड्स की पूरी सूची के लिए इवेंट्स कैटलॉग देखें।

सिग्नेचर सत्यापन

हर रिक्वेस्ट में X-ThunderPhone-Signature हेडर में रॉ रिक्वेस्ट बॉडी पर एक HMAC-SHA256 सिग्नेचर होता है। साइनिंग key एंडपॉइंट का secret है (या लेगेसी डिलीवरी के लिए आपका संगठन-स्तरीय webhook secret)।

चरण

  1. किसी भी पार्सिंग से पहले रॉ रिक्वेस्ट बॉडी पढ़ें।
  2. hmac_sha256(secret, body).hexdigest() की गणना करें।
  3. X-ThunderPhone-Signature हेडर से कॉन्स्टेंट टाइम में तुलना करें।
हम ठीक वही बाइट्स साइन करते हैं जो हम भेजते हैं, और वे बाइट्स कैनॉनिकल JSON सीरियलाइज़ेशन हैं (सॉर्ट की गई keys, कॉम्पैक्ट सेपरेटर)। इसलिए रॉ बॉडी के विरुद्ध सत्यापन हमेशा काम करता है — और यदि आपका फ्रेमवर्क आपको केवल पार्स किया हुआ JSON देता है, तो उसे सॉर्ट की गई keys और कॉम्पैक्ट सेपरेटर के साथ फिर से सीरियलाइज़ करने पर समान बाइट्स बनती हैं। दोनों रेसिपी सत्यापन गाइड में दी गई हैं।

डिलीवरी सेमांटिक्स

ये सेमांटिक्स endpoint डिलीवरी पर लागू होते हैं। लेगेसी single-URL webhook बिना रिट्राई के एक ही synchronous प्रयास करता है।
हर इवेंट का तुरंत एक बार प्रयास किया जाता है। कोई भी 2xx रिस्पॉन्स डिलीवरी को स्वीकार करता है। किसी भी अन्य परिणाम (non-2xx, कनेक्शन त्रुटि, timeout) पर हम पहले प्रयास के 1 m, 5 m, 30 m, 2 h, 6 h, 12 h, और 24 h बाद रिट्राई करते हैं — 24 घंटों में 8 प्रयास। यदि हर प्रयास विफल हो जाता है, तो डिलीवरी रुक जाती है और endpoint को webhook endpoints में status="failing" के रूप में चिह्नित किया जाता है। पेलोड को स्थायी रूप से स्वीकार करते ही 2xx लौटाएँ; asynchronous रूप से प्रोसेस करें।
डिलीवरी क्रम best-effort है। व्यवहार में हम इवेंट को उनके emit होने के क्रम में डिलीवर करते हैं, लेकिन विफलता पर रिट्राई क्रम बदल सकते हैं। हमेशा call_id / object id के आधार पर dedup और reconcile करें।
डिलीवरी at-least-once है: ऐसे रिस्पॉन्स के बाद रिट्राई, जो हमें कभी नहीं मिला, किसी इवेंट को डुप्लिकेट कर सकता है। हर रिट्राई में वही event_id होता है, इसलिए प्रोसेस किए गए ids स्टोर करें और दोहराव छोड़ दें। event_id endpoints के बीच भी साझा होता है — एक ही इवेंट को subscribe किए गए दो endpoints को वही event_id मिलता है।
Endpoint डिलीवरी में प्रत्येक प्रयास के लिए 30 s timeout होता है। लेगेसी पथ पर, लाइव कॉल व्यवहार नियंत्रित करने वाले blocking requests — telephony.incoming / web.incoming configuration exchange — 10 s के बाद timeout हो जाते हैं, लेकिन धीमा रिस्पॉन्स कॉल पिकअप में देरी करता है, इसलिए कुछ सेकंड के भीतर उत्तर देने का लक्ष्य रखें। Webhook-mode tool dispatch 20 s की अनुमति देता है।
आउटबाउंड webhooks ThunderPhone की cloud IP रेंज से उत्पन्न होते हैं। यदि आपके firewall को allowlist की आवश्यकता है, तो support से संपर्क करें और हम वर्तमान रेंज साझा करेंगे।

लेगेसी और endpoint-आधारित webhooks के बीच चयन

नई integrations को endpoint-आधारित webhooks के माध्यम से इवेंट consume करने चाहिए। लेगेसी URL केवल तभी रखें (या जोड़ें) जब आप कॉल को पिकअप समय पर डायनामिक रूप से configure करते हैं या webhook-mode tool dispatch का उपयोग करते हैं — वे request/response exchanges केवल लेगेसी पथ पर चलते हैं।

संबंधित

इवेंट कैटलॉग

सभी इवेंट प्रकार और उनके पेलोड।

Webhook endpoints

कई endpoints, इवेंट फ़िल्टर और secrets प्रबंधित करें।

telephony.incoming / web.incoming

कॉल configure करने के लिए आपके सर्वर को जिस blocking request का उत्तर देना होगा।

telephony.complete / web.complete

ट्रांसक्रिप्ट, रिकॉर्डिंग और metrics के साथ कॉल के बाद का पेलोड।