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

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

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

دستخط کی توثیق#

ہر درخواست میں 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 webhook ایک ہی ہم وقت کوشش ہے، جس میں دوبارہ کوششیں نہیں ہوتیں۔

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

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

متعلقہ#