ویب ہکس کا جائزہ

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 استعمال ہوتا ہے۔ ان دستاویزات میں خوب صورت انداز سے فارمیٹ کی گئی مثالیں صرف پڑھنے میں آسانی کے لیے ہیں۔

ایونٹ اقسام اور پے لوڈ فیلڈز کی مکمل فہرست کے لیے ایونٹس کیٹلاگ دیکھیں۔

دستخط کی تصدیق#

ہر درخواست میں دو دستخط شامل ہوتے ہیں، دونوں endpoint کے secret (یا پرانی ڈیلیوریز کے لیے آپ کے تنظیمی سطح کے webhook secret) کے ساتھ HMAC-SHA256 استعمال کرتے ہیں:

• X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<hex> ٹائم اسٹیمپ، طریقہ، path اور query، اور خام body پر دستخط کرتا ہے۔ اس کی تصدیق کریں، اور ان درخواستوں کو مسترد کریں جن کا t آپ کی گھڑی سے 5 منٹ سے زیادہ مختلف ہو، تاکہ پکڑی گئی درخواست کو بعد میں دوبارہ چلایا نہ جا سکے۔ دوبارہ کوششیں بھیجے جانے پر دوبارہ دستخط کی جاتی ہیں۔
• X-ThunderPhone-Signature صرف خام body پر دستخط کرتا ہے۔ اسے بغیر تبدیلی کے اب بھی بھیجا جاتا ہے تاکہ موجودہ تصدیق کنندگان کام کرتے رہیں۔

مراحل#

1. ہیڈر، طریقہ، خام path اور query، اور خام body کو کسی بھی parsing سے پہلے پڑھیں۔
2. اپنے secret کے ساتھ <t>\n<METHOD>\n<path and query>\n<body> کا hex HMAC-SHA256 حساب کریں۔
3. اگر t میں 300 سیکنڈ سے زیادہ فرق ہو، یا نتیجہ مستقل وقت کے تقابل میں v1 سے مطابقت نہ رکھتا ہو، تو درخواست مسترد کریں۔

Bodies معیاری JSON سیریلائزیشن ہیں (ترتیب شدہ کلیدیں، مختصر جداکار)، اور ہم بالکل انہی بائٹس پر دستخط کرتے ہیں جو ہم منتقل کرتے ہیں۔ تصدیق کا رہنما میں دستخط شدہ عین سٹرنگ، ایک عملی مثال، SDK کے بغیر کوڈ، اور پرانا ہیڈر شامل ہیں۔

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);
  },
);

ترسیل کی معنویات#

یہ semantics اینڈپوائنٹ ڈیلیوریز پر لاگو ہوتے ہیں۔ پرانا واحد-URL ویب ہک دوبارہ کوششوں کے بغیر ایک ہی synchronous کوشش ہے، سوائے فون کال کے telephony.incoming configuration تبادلے کے، جس کی ایک بار دوبارہ کوشش کی جاتی ہے۔

لیگیسی اور اینڈپوائنٹ پر مبنی ویب ہکس کے درمیان انتخاب#

نئی انٹیگریشنز کو اینڈپوائنٹ پر مبنی ویب ہکس کے ذریعے ایونٹس استعمال کرنے چاہییں۔ لیگیسی URL صرف اسی صورت میں رکھیں (یا شامل کریں) جب آپ کال اٹھانے کے وقت کالز کو متحرک طور پر کنفیگر کرتے ہوں یا ویب ہک موڈ ٹول ڈسپیچ استعمال کرتے ہوں — یہ درخواست/جواب تبادلے صرف لیگیسی راستے پر چلتے ہیں۔

متعلقہ#