Webhooks

वेबहुक्स का अवलोकन

ThunderPhone रीयल-टाइम इवेंट्स कैसे डिलीवर करता है, सिग्नेचर कैसे सत्यापित करें, और लेगेसी तथा एंडपॉइंट-आधारित डिलीवरी मॉडल की तुलना।

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

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

पेलोड फ़ॉर्मैट#

एंडपॉइंट डिलीवरी data, event_id, और type वाला एक JSON ऑब्जेक्ट है:

{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}

event_id हर एमिट किए गए इवेंट के लिए यूनिक है। यह रीट्राइ के दौरान और इवेंट प्राप्त करने वाले प्रत्येक एंडपॉइंट पर समान रहता है — इसी पर डीडुप्लिकेट करें।

लेगसी सिंगल-URL वेबहुक समान type और data भेजता है, लेकिन event_id के बिना:

{
  "type": "telephony.incoming",
  "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567" }
}

नेटवर्क पर, प्रत्येक बॉडी कैनॉनिकली सीरियलाइज़ होती है — कुंजियाँ वर्णानुक्रम में सॉर्ट की जाती हैं, कोई व्हाइटस्पेस नहीं होता, और UTF-8 का उपयोग होता है। इन डॉक्स में प्रिटी-प्रिंट किए गए उदाहरण केवल पठनीयता के लिए हैं।

इवेंट प्रकारों और पेलोड फ़ील्ड की पूरी सूची के लिए इवेंट्स कैटलॉग देखें।

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

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

चरण#

1. किसी भी पार्सिंग से पहले रॉ रिक्वेस्ट बॉडी पढ़ें।
2. hmac_sha256(secret, body).hexdigest() कैलकुलेट करें।
3. X-ThunderPhone-Signature हेडर से कॉन्स्टेंट टाइम में तुलना करें।

हम ठीक उन्हीं बाइट्स पर साइन करते हैं जिन्हें हम भेजते हैं, और वे बाइट्स कैनोनिकल JSON सीरियलाइज़ेशन हैं (सॉर्ट कीज़, कॉम्पैक्ट सेपरेटर)। इसलिए रॉ बॉडी के विरुद्ध सत्यापन हमेशा काम करता है — और यदि आपका फ्रेमवर्क आपको केवल पार्स किया हुआ JSON देता है, तो उसे सॉर्ट कीज़ और कॉम्पैक्ट सेपरेटर के साथ फिर से सीरियलाइज़ करने पर समान बाइट्स मिलती हैं। दोनों तरीके सत्यापन गाइड में शामिल हैं।

import hmac
import hashlib
 
def verify_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature or "")
 
# Example Flask handler
from flask import Flask, request, abort
app = Flask(__name__)
 
@app.post("/thunderphone-webhook")
def handle():
    body = request.get_data()
    sig = request.headers.get("X-ThunderPhone-Signature", "")
    if not verify_signature(body, sig, WEBHOOK_SECRET):
        abort(401)
    event = request.get_json()
    # dispatch on event["type"] …
    return "", 204

import crypto from "node:crypto";
import express from "express";
 
function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  if (!signature || expected.length !== signature.length) return false;
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature),
  );
}
 
const app = express();
app.post(
  "/thunderphone-webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const sig = req.header("X-ThunderPhone-Signature") || "";
    if (!verifySignature(req.body, sig, process.env.WEBHOOK_SECRET)) {
      return res.sendStatus(401);
    }
    const event = JSON.parse(req.body.toString("utf8"));
    // dispatch on event.type …
    res.sendStatus(204);
  },
);

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

ये सेमांटिक्स एंडपॉइंट डिलीवरी पर लागू होते हैं। लेगेसी सिंगल-URL वेबहुक बिना किसी पुनः प्रयास के एकल सिंक्रोनस प्रयास है।

लेगेसी और एंडपॉइंट-आधारित वेबहुक के बीच चयन#

नए इंटीग्रेशन को एंडपॉइंट-आधारित वेबहुक के माध्यम से इवेंट्स का उपभोग करना चाहिए। लेगेसी URL केवल तभी रखें (या जोड़ें) जब आप कॉल पिकअप के समय कॉल को डायनेमिक रूप से कॉन्फ़िगर करते हैं या वेबहुक-मोड टूल डिस्पैच का उपयोग करते हैं — वे रिक्वेस्ट/रिस्पॉन्स एक्सचेंज केवल लेगेसी पथ पर चलते हैं।

संबंधित#