Webhook एंडपॉइंट्स

प्रत्येक एंडपॉइंट के लिए सीक्रेट्स और इवेंट फ़िल्टर के साथ कई webhook URLs प्रबंधित करें।

एंडपॉइंट-आधारित वेबहुक सिस्टम आपको प्रति संगठन कई डेस्टिनेशन रजिस्टर करने देता है, जिनमें से प्रत्येक का अपना सीक्रेट, अपना स्टेटस, और इवेंट प्रकारों के एक सबसेट के लिए अपना सब्सक्रिप्शन होता है। यह सभी नए इंटीग्रेशन के लिए अनुशंसित मॉडल है।

लीगेसी सिंगल-URL वेबहुक से तुलना करें, जिसे बैकवर्ड कंपैटिबिलिटी के लिए रखा गया है, लेकिन यह प्रति संगठन केवल एक URL सपोर्ट करता है।

एंडपॉइंट्स#

एंडपॉइंट ऑब्जेक्ट#

{
  "id": "c4d5e6f7-...",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "agent_id": 42,
  "agent_name": "Support Agent",
  "secret_hint": "a1b2…9f0e",
  "paused_at": null,
  "pause_last_error": "",
  "pause_undelivered_count": null,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

मान्य इवेंट टाइप#

events को इसी सटीक सेट के आधार पर वैलिडेट किया जाता है — सूची के बाहर की वैल्यू 400 लौटाती हैं। हर टाइप के पेलोड स्ट्रक्चर के लिए इवेंट्स कैटलॉग देखें।

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• sms.sent, sms.failed
• sms.received (आरक्षित; अभी तक एमिट नहीं किया गया)
• call.graded, call.data_extracted, call.transfer_completed
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

issue.escalated में कोई एजेंट कॉन्टेक्स्ट नहीं होता और इसे केवल संगठन-व्यापी एंडपॉइंट्स पर डिलीवर किया जाता है।

voice.ready और voice.failed को स्पष्ट रूप से नहीं चुना जा सकता। इन्हें पाने के लिए, events: [] के साथ एक संगठन-व्यापी एंडपॉइंट बनाएं। एक खाली इवेंट सूची telephony.turn और web.turn को छोड़कर हर समर्थित इवेंट प्राप्त करती है, जिन्हें स्पष्ट रूप से चुनना आवश्यक है।

एंडपॉइंट स्टेटस#

• active — डिलीवरी सामान्य रूप से प्रवाहित होती हैं।
• disabled — PATCH के माध्यम से मैन्युअली पॉज़ किया गया। कोई अनुरोध नहीं भेजा जाता। हम कभी भी disabled एंडपॉइंट का स्टेटस नहीं बदलते; इसे वापस active करना हमेशा आपका निर्णय है।
• failing — जब एंडपॉइंट पर की गई डिलीवरी बिना कभी 2xx प्राप्त किए अपने पूरे रीट्राई शेड्यूल (24 घंटों में 8 प्रयास) को समाप्त कर देती है, तो यह अपने-आप सेट हो जाता है। फेल हो रहे एंडपॉइंट को आगे कोई ट्रैफ़िक नहीं मिलता। ऐसा होने पर हम आपके संगठन के ओनर्स और एडमिन्स को ईमेल भेजते हैं, और डैशबोर्ड पॉज़ किए गए एंडपॉइंट को Re-activate बटन के साथ दिखाता है। एंडपॉइंट ठीक हो जाने पर, PATCH के माध्यम से उसका स्टेटस वापस active करें; जिन डिलीवरी का रीट्राई शेड्यूल अभी समाप्त नहीं हुआ है, वे वहीं से फिर शुरू होती हैं जहाँ वे रुकी थीं।

एंडपॉइंट्स की सूची#

curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

एंडपॉइंट ऑब्जेक्ट्स की एक array लौटाता है। केवल उस एजेंट के लिए स्कोप किए गए एंडपॉइंट्स लौटाने के लिए ?agent_id=42 पास करें।

एजेंट-स्कोप्ड एंडपॉइंट्स#

संगठन-व्यापी एंडपॉइंट्स हर मैचिंग इवेंट प्राप्त करते हैं। agent_id वाला एंडपॉइंट केवल उस एजेंट द्वारा संभाले गए कॉल्स के मैचिंग इवेंट्स प्राप्त करता है; एजेंट कॉन्टेक्स्ट के बिना इवेंट्स, जैसे alert.triggered, उस तक कभी नहीं पहुंचते। आप इन एंडपॉइंट्स को एजेंट बिल्डर के वेबहुक्स सेक्शन से भी बना और मैनेज कर सकते हैं।

एक एंडपॉइंट बनाएं#

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call events",
    "url":    "https://example.com/thunderphone/hook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'

result = requests.post(
    "https://api.thunderphone.com/v1/developer/webhook-endpoints",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "label":  "Production — Call events",
        "url":    "https://example.com/thunderphone/hook",
        "events": ["telephony.incoming", "telephony.complete"],
    },
).json()
secret = result["secret"]
endpoint_id = result["id"]

रिक्वेस्ट फ़ील्ड#

एंडपॉइंट ऑब्जेक्ट के साथ 201 Created लौटाता है, साथ ही एक अतिरिक्त टॉप-लेवल secret फ़ील्ड लौटाता है जिसमें रॉ साइनिंग की होती है — एक 48-कैरेक्टर हेक्स स्ट्रिंग:

{
  "id": "c4d5e6f7-…",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "a1b2…9f0e",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z",
  "secret": "a1b2c37e08d94f5b16a2c8d90e7f3a4b5c6d7e8f90a19f0e"
}

एक एंडपॉइंट अपडेट करें#

curl -X PATCH https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call + Grade events",
    "events": ["telephony.incoming", "telephony.complete", "call.graded"]
  }'

अपडेट किए गए एंडपॉइंट ऑब्जेक्ट के साथ 200 OK लौटाता है।

साइनिंग सीक्रेट रोटेट करें#

किसी एंडपॉइंट का साइनिंग सीक्रेट बदलें, उदाहरण के लिए जब वह खो गया हो या लीक हो गया हो। एजेंट-स्कोप वाले एंडपॉइंट के लिए आप डैशबोर्ड भी उपयोग कर सकते हैं: एजेंट का वेबहुक्स सेक्शन खोलें और एंडपॉइंट पर सीक्रेट रीजनरेट करें चुनें। संगठन-व्यापी एंडपॉइंट API के माध्यम से रोटेट किए जाते हैं।

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

200 OK लौटाता है:

{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}

एक टेस्ट डिलीवरी भेजें#

सामान्य डिलीवरी पाइपलाइन का उपयोग करके एक एंडपॉइंट पर सिंथेटिक webhook.test इवेंट भेजें, जिसमें कैनोनिकल JSON सीरियलाइज़ेशन, दोनों सिग्नेचर हेडर, डिलीवरी रिकॉर्डिंग और रीट्राई बुककीपिंग शामिल हों। टेस्ट अपने events फ़िल्टर की परवाह किए बिना चुने गए एंडपॉइंट को लक्षित करता है।

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

एंडपॉइंट को इस तरह का एक एनवेलप मिलता है:

{
  "data": {
    "message": "ThunderPhone webhook test",
    "sent_at": "2026-07-17T20:12:34.567890+00:00"
  },
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "type": "webhook.test"
}

डेस्टिनेशन द्वारा एरर लौटाने पर भी API पहले प्रयास के बाद 200 OK लौटाता है। डिलीवरी परिणाम के लिए success, status, response_code, और error देखें:

{
  "success": true,
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "event_type": "webhook.test",
  "status": "delivered",
  "response_code": 204,
  "error": ""
}

webhook.test सिंथेटिक है और इसे किसी एंडपॉइंट की events सब्सक्रिप्शन में नहीं जोड़ा जा सकता। अगर पहला प्रयास विफल होता है, तो ThunderPhone लगभग एक मिनट बाद एक बार रीट्राई करता है और फिर रुक जाता है; डिलीवरी फिर डिलीवरी डीबग करें में status: "failed" दिखाती है। टेस्ट डिलीवरी कभी भी एंडपॉइंट को failing के रूप में मार्क नहीं करती।

किसी वास्तविक इवेंट संरचना के विरुद्ध ट्रिगर कॉन्फ़िगर करने के लिए, वैकल्पिक event_type पास करें। डिलीवरी फिर भी सिंथेटिक रहती है और इसमें "sample": true होता है; कॉल-संबंधित सैंपल में call_id: 0 और agent_id: 0 का उपयोग होता है।

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"call.graded"}'

event_type, मान्य इवेंट प्रकारों में से कोई भी वैल्यू स्वीकार करता है। इसे छोड़ने पर सामान्य webhook.test व्यवहार बना रहता है।

एक एंडपॉइंट हटाएं#

curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

204 No Content लौटाता है। URL पर डिलीवरी तुरंत रुक जाती है; इन-फ्लाइट रीट्राई छोड़ दिए जाते हैं।

डिलीवरी डीबग करें#

यह निष्कर्ष निकालने से पहले कि कोई वेबहुक नहीं भेजा गया था, GET /v1/developer/webhook-deliveries देखें। यह दोनों वेबहुक सिस्टम के हालिया प्रयास दिखाता है, जिनमें कॉल आईडी, URL ओरिजिन, HTTP स्टेटस, प्रयासों की संख्या, अलाउलिस्टेड विफलता श्रेणी और अगला रीट्राई समय शामिल हैं। यह कभी भी इवेंट पेलोड, ट्रांसक्रिप्ट, स्टोर किया गया एरर टेक्स्ट, रिस्पॉन्स बॉडी या URL पाथ नहीं लौटाता।

आप यही हालिया हिस्ट्री एजेंट्स → एक एजेंट चुनें → वेबहुक्स → हालिया डिलीवरी में भी देख सकते हैं। पंक्तियां एंडपॉइंट लेबल और नवीनतम प्रयास द्वारा उपयोग किया गया URL ओरिजिन दिखाती हैं। यह अपरिवर्तनीय ऑडिट लॉग के बजाय ऑपरेशनल स्टेट है: एंडपॉइंट हटाने पर उसकी डिलीवरी पंक्तियां भी हट जाती हैं।

n8n 404 के लिए, पहले पुष्टि करें कि वर्कफ़्लो सक्रिय है, POST स्वीकार करता है और टेस्ट URL के बजाय प्रोडक्शन वेबहुक URL का उपयोग करता है। 401 या 403 ऑथेंटिकेशन या सिग्नेचर वैलिडेशन की ओर संकेत करता है; टाइमआउट डेस्टिनेशन लेटेंसी या उपलब्धता की ओर संकेत करते हैं; TLS एरर सर्टिफ़िकेट चेन, होस्टनेम या समाप्ति की ओर संकेत करते हैं।

संबंधित#