वेबहुक्सचा आढावा

ThunderPhone रिअल-टाइम इव्हेंट्स कसे वितरित करते, स्वाक्षऱ्या कशा पडताळायच्या आणि लेगसी व एंडपॉइंट-आधारित वितरण मॉडेल्सची तुलना कशी होते.

ThunderPhone कॉलदरम्यान घटना घडल्यावर तुमच्या सर्व्हरला HTTP POST विनंत्या पाठवते — इनबाउंड कॉल सुरू होतो, कॉल संपतो, ग्रेडिंग रन पूर्ण होते, अलर्ट ट्रिगर होतो इत्यादी. दोन वितरण मॉडेल्स आहेत:

इव्हेंट्स कॅटलॉग मधील सर्व दहा इव्हेंट प्रकार webhook एंडपॉइंट्सद्वारे वितरित केले जातात. सहा कॉल-लाइफसायकल इव्हेंट्स (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) तसेच लेगसी सिंगल-URL webhook वर पाठवले जातात — तुमच्याकडे लेगसी URL आणि जुळणारा एंडपॉइंट दोन्ही असल्यास, तुम्हाला इव्हेंट दोन्ही मार्गांवर प्राप्त होतो. अवरोधक वर्तन (telephony.incoming / web.incoming कॉन्फिगरेशन एक्सचेंज आणि webhook-मोड टूल डिस्पॅच) केवळ लेगसी मार्गावर असते; प्रत्येक एंडपॉइंट वितरण फायर-अँड-फॉरगेट सूचना असते.

पेलोड स्वरूप#

एंडपॉइंट वितरणांमध्ये 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 webhook तोच 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 ठेवा (किंवा जोडा) — त्या विनंती/प्रतिसाद देवाणघेवाणी फक्त जुन्या मार्गावर चालतात.

संबंधित#