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

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. या दस्तऐवजांमधील सुंदर स्वरूपातील उदाहरणे केवळ वाचनीयतेसाठी आहेत.

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

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

प्रत्येक विनंतीमध्ये दोन स्वाक्षऱ्या असतात. दोन्ही endpoint च्या secret ने HMAC-SHA256 की केलेल्या असतात (किंवा legacy वितरणांसाठी तुमच्या संस्थास्तरीय webhook secret ने):

• X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<hex> टाइमस्टॅम्प, पद्धत, पथ व क्वेरी आणि रॉ बॉडीवर स्वाक्षरी करते. ही तपासा आणि ज्या विनंत्यांमधील t तुमच्या घड्याळापेक्षा 5 मिनिटांपेक्षा जास्त फरकाचा आहे त्या नाकारा, जेणेकरून पकडलेली विनंती नंतर पुन्हा पाठवता येणार नाही. रिट्राय पाठवताना त्यांवर पुन्हा स्वाक्षरी केली जाते.
• X-ThunderPhone-Signature फक्त रॉ बॉडीवर स्वाक्षरी करते. विद्यमान पडताळक कार्यरत राहावेत म्हणून ती अजूनही बदल न करता पाठवली जाते.

पायऱ्या#

1. कोणतेही parsing करण्यापूर्वी header, method, raw path आणि query, तसेच raw body वाचा.
2. तुमच्या secret सह <t>\n<METHOD>\n<path and query>\n<body> चे hex HMAC-SHA256 गणना करा.
3. t 300 सेकंदांपेक्षा जास्त फरकाने दूर असल्यास किंवा constant-time तुलनेत परिणाम v1 शी जुळत नसल्यास विनंती नाकारा.

Bodies हे canonical JSON serialization (क्रमबद्ध keys, compact separators) आहेत आणि आम्ही पाठवतो तेच bytes नेमके sign करतो. सत्यापन मार्गदर्शक मध्ये अचूक signed string, कार्य केलेले उदाहरण, SDK शिवायचा code आणि legacy header आहे.

from flask import Flask, abort, request
from thunderphone import verify_signature
 
app = Flask(__name__)
 
@app.post("/thunderphone-webhook")
def handle():
    query = request.query_string.decode()
    if not verify_signature(
        request.headers.get("X-ThunderPhone-Signature-V2"),
        secret=WEBHOOK_SECRET,
        method=request.method,
        path=request.path + (f"?{query}" if query else ""),
        body=request.get_data(),  # raw bytes
    ):
        abort(401)
    event = request.get_json()
    # dispatch on event["type"] …
    return "", 204

import express from "express";
import { verifySignature } from "@thunderphone/sdk";
 
const app = express();
app.post(
  "/thunderphone-webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const ok = verifySignature({
      header: req.header("X-ThunderPhone-Signature-V2"),
      secret: process.env.WEBHOOK_SECRET,
      method: req.method,
      path: req.originalUrl,
      body: req.body,
    });
    if (!ok) return res.sendStatus(401);
    const event = JSON.parse(req.body.toString("utf8"));
    // dispatch on event.type …
    res.sendStatus(204);
  },
);

वितरण अर्थविषयक नियम#

हे नियम एंडपॉइंट वितरणांना लागू होतात. लेगसी सिंगल-URL webhook हा पुनःप्रयत्नांशिवाय एक समकालिक प्रयत्न असतो, अपवाद म्हणजे फोन-कॉल telephony.incoming कॉन्फिगरेशन एक्सचेंज, ज्याचा एकदा पुनःप्रयत्न केला जातो.

लेगसी आणि एंडपॉइंट-आधारित webhooks यांपैकी निवडणे#

नवीन एकत्रीकरणांनी एंडपॉइंट-आधारित webhooks द्वारे इव्हेंट वापरावेत. फक्त कॉल उचलतानाच्या वेळी तुम्ही कॉल डायनॅमिकरीत्या कॉन्फिगर करत असल्यास किंवा webhook-मोड टूल डिस्पॅच वापरत असल्यास लेगसी URL ठेवा (किंवा जोडा) — त्या विनंती/प्रतिसाद देवाणघेवाणी फक्त लेगसी मार्गावर चालतात.

संबंधित#