Webhooks-এর সংক্ষিপ্ত বিবরণ

ThunderPhone কল চলাকালে বিভিন্ন ঘটনা ঘটলে আপনার সার্ভারে HTTP POST অনুরোধ পাঠায় — একটি ইনবাউন্ড কল শুরু হয়, একটি কল শেষ হয়, একটি গ্রেডিং রান সম্পন্ন হয়, একটি সতর্কতা ট্রিগার হয়, ইত্যাদি। দুটি ডেলিভারি মডেল রয়েছে:

ইভেন্ট ক্যাটালগে থাকা সব দশটি ইভেন্ট টাইপ webhook এন্ডপয়েন্টের মাধ্যমে ডেলিভার করা হয়। ছয়টি কল-লাইফসাইকেল ইভেন্ট (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) লিগ্যাসি একক-URL webhook-এও পাঠানো হয় — আপনার যদি একটি লিগ্যাসি URL এবং একটি মিলযুক্ত এন্ডপয়েন্ট উভয়ই থাকে, তাহলে আপনি উভয় পাথেই ইভেন্টটি পাবেন। ব্লকিং আচরণ (telephony.incoming / web.incoming কনফিগারেশন বিনিময় এবং webhook-মোডের টুল ডিসপ্যাচ) একচেটিয়াভাবে লিগ্যাসি পাথে থাকে; প্রতিটি এন্ডপয়েন্ট ডেলিভারি হলো fire-and-forget বিজ্ঞপ্তি।

পেলোড ফরম্যাট

এন্ডপয়েন্ট ডেলিভারি হলো 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। এই ডকুমেন্টেশনের সুন্দরভাবে ফরম্যাট করা উদাহরণগুলো শুধুমাত্র পাঠযোগ্যতার জন্য।

ইভেন্ট টাইপ এবং পেলোড ফিল্ডের সম্পূর্ণ তালিকার জন্য ইভেন্ট ক্যাটালগ দেখুন।

স্বাক্ষর যাচাইকরণ

প্রতিটি অনুরোধে 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 রাখুন (অথবা যোগ করুন) — এই অনুরোধ/প্রতিক্রিয়া বিনিময়গুলো কেবল লিগ্যাসি পথেই চলে।

সম্পর্কিত