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

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 प्रत्येक उत्सर्जित इव्हेंटसाठी अद्वितीय असतो. तो retriesमध्ये आणि इव्हेंट प्राप्त करणाऱ्या प्रत्येक एंडपॉइंटमध्ये एकसारखा असतो — त्यावर dedup करा.

लेगसी एकल-URL वेबहुक समान type आणि data पाठवते, परंतु event_id शिवाय:

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

वायरवर, प्रत्येक body कॅनॉनिकली सिरियलाइझ केला जातो — keys वर्णक्रमानुसार क्रमबद्ध, रिक्त जागा नाहीत, UTF-8. या दस्तऐवजांमधील नीट फॉरमॅट केलेली उदाहरणे केवळ वाचनीयतेसाठी आहेत.

इव्हेंट प्रकार आणि पेलोड फील्ड्सच्या संपूर्ण यादीसाठी इव्हेंट्स कॅटलॉग पहा.

स्वाक्षरी पडताळणी

प्रत्येक विनंतीमध्ये X-ThunderPhone-Signature हेडरमध्ये कच्च्या विनंती मुख्यभागावर HMAC-SHA256 स्वाक्षरी असते. स्वाक्षरीकरण की म्हणजे एंडपॉइंटचा secret (किंवा जुन्या वितरणांसाठी तुमच्या संस्थास्तरीय webhook 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 ठेवा (किंवा जोडा) — ते विनंती/प्रतिसाद एक्सचेंज फक्त लेगसी मार्गावर चालतात.

संबंधित