Webhooks

वेबहुक एंडपॉइंट्स

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

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

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

एंडपॉइंट#

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

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

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

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

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• call.graded
• issue.reported
• test-call.completed
• alert.triggered

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

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

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

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

एंडपॉइंट ऑब्जेक्ट की एक ऐरे लौटाता है।

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

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 लौटाता है।

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

कैनॉनिकल JSON सीरियलाइज़ेशन, X-ThunderPhone-Signature, डिलीवरी रिकॉर्डिंग और रिट्राई बुककीपिंग सहित, सामान्य डिलीवरी पाइपलाइन का उपयोग करके एक एंडपॉइंट पर सिंथेटिक webhook.test इवेंट भेजें। टेस्ट उसके 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 सब्सक्रिप्शन में जोड़ा नहीं जा सकता। पहला प्रयास विफल होने पर, डिलीवरी सामान्य इवेंट डिलीवरी के समान रिट्राई शेड्यूल का पालन करती है।

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

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

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

संबंधित#