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

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" }
}

ترسیل کے دوران، ہر باڈی معیاری طور پر سریلائز کی جاتی ہے — keys حروف تہجی کے لحاظ سے ترتیب دی جاتی ہیں، کوئی whitespace نہیں ہوتا، اور UTF-8 استعمال ہوتا ہے۔ ان دستاویزات میں خوب صورت فارمیٹ کیے گئے نمونے صرف پڑھنے میں آسانی کے لیے ہیں۔

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

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

ہر درخواست میں X-ThunderPhone-Signature ہیڈر میں خام درخواست باڈی پر HMAC-SHA256 دستخط شامل ہوتا ہے۔ دستخطی کلید endpoint کا secret ہے (یا legacy ڈیلیوریز کے لیے آپ کی تنظیمی سطح کے webhook کا secret)۔

مراحل

1. کسی بھی parsing سے پہلے خام درخواست باڈی پڑھیں۔
2. hmac_sha256(secret, body).hexdigest() کا حساب کریں۔
3. X-ThunderPhone-Signature ہیڈر کے ساتھ مستقل وقت میں موازنہ کریں۔

ہم بالکل وہی بائٹس دستخط کرتے ہیں جو ہم منتقل کرتے ہیں، اور وہ بائٹس canonical JSON serialization ہیں (ترتیب شدہ keys، مختصر separators)۔ لہٰذا خام باڈی کے خلاف تصدیق ہمیشہ کام کرتی ہے — اور اگر آپ کا framework آپ کو صرف parsed JSON دیتا ہے تو اسے ترتیب شدہ keys اور مختصر separators کے ساتھ دوبارہ serialize کرنے سے یکساں بائٹس تیار ہوتے ہیں۔ دونوں طریقے تصدیقی گائیڈ میں شامل ہیں۔

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 صرف اسی صورت میں رکھیں (یا شامل کریں) جب آپ پک اپ کے وقت کالز کو متحرک طور پر کنفیگر کرتے ہوں یا ویب ہک موڈ ٹول ڈسپیچ استعمال کرتے ہوں — یہ درخواست/جواب تبادلے صرف لیگیسی راستے پر چلتے ہیں۔

متعلقہ