ThunderPhone v3 এখন লাইভ।নিজেই ব্যবহার শুরু করুন, 2¢/মিনিট থেকে।ঘোষণাটি পড়ুন

Operations

ওয়েবহুক স্বাক্ষর যাচাই করুন

ThunderPhone পাঠানো প্রতিটি ওয়েবহুক ও টুল অনুরোধে একটি টাইমস্ট্যাম্পসহ স্বাক্ষর থাকে। এখানকার রেসিপি বা SDK সহায়ক দিয়ে এটি যাচাই করুন এবং পাঁচ মিনিটের বেশি পুরোনো পুনরায় পাঠানো অনুরোধ প্রত্যাখ্যান করুন।

আপনার সার্ভারে আমরা পাঠানো প্রতিটি অনুরোধে (webhook ডেলিভারি, লিগ্যাসি single-URL webhook এবং tool-endpoint কল) দুটি স্বাক্ষর হেডার থাকে। উভয়ই একই secret সহ HMAC-SHA256।

হেডারযে ডেটায় স্বাক্ষর করেরিপ্লে সুরক্ষা
X-ThunderPhone-Signature-V2 (প্রস্তাবিত)Timestamp, method, path, query এবং body5 মিনিটের বেশি পুরোনো অনুরোধ প্রত্যাখ্যান করুন
X-ThunderPhone-Signatureশুধু bodyকোনোটি নয়: ধরা পড়া একটি অনুরোধ চিরকাল যাচাই হয়

নতুন ইন্টিগ্রেশনে X-ThunderPhone-Signature-V2 যাচাই করুন এবং বিদ্যমান ইন্টিগ্রেশনগুলো এতে স্থানান্তর করুন। X-ThunderPhone-Signature এখনও প্রতিটি অনুরোধে অপরিবর্তিতভাবে পাঠানো হয়, তাই এর ওপর নির্মিত verifier-গুলো কাজ করতে থাকবে। এটি পাঠানো বন্ধ করার আগে আমরা একটি তারিখ ঘোষণা করব।

সিগনেচার V2

X-ThunderPhone-Signature-V2: t=1767225600,v1=03a89bec521f78d55727237ca4713bb0b8dcdf2e09e450865b5b5637b80c1c4e
  • t হলো Unix সময়, সেকেন্ডে, যখন আমরা অনুরোধটি পাঠিয়েছি। পুনরায় চেষ্টা করা ডেলিভারি পাঠানোর সময় আবার সাইন করা হয়, যার নিজস্ব t থাকে।
  • v1 হলো নিচের সাইন করা স্ট্রিংয়ের hex HMAC-SHA256, যা আপনার secret দিয়ে কী করা।

মানটি key=value জোড়ার কমা-বিভক্ত তালিকা। আপনি যেসব key শনাক্ত করেন না সেগুলো উপেক্ষা করুন, এবং যেকোনো v1 মিললে অনুরোধটি গ্রহণ করুন: ভবিষ্যতের কোনো পরিবর্তনের সময় আমরা দ্বিতীয় একটি সিগনেচার যোগ করতে পারি।

সাইন করা স্ট্রিং

চারটি ফিল্ড, প্রতিটির পরে একটি newline (\n, byte 0x0A), শেষটি ছাড়া:

<t>\n<METHOD>\n<path and query>\n<body>
ফিল্ডমান
theader থেকে পাওয়া t মান
METHODবড় হাতের HTTP method: POST, GET, PUT, PATCH অথবা DELETE
path and queryHTTP request line থেকে request target: path, তারপর ? এবং থাকলে query string। কোনো scheme, host বা fragment নয়। ডিকোড না করে বা parameter পুনর্বিন্যাস না করে, যেভাবে এসেছে ঠিক সেভাবেই ব্যবহার করুন
bodyraw request body। GET এবং DELETE tool call-এর কোনো body নেই, তাই তাদের সাইন করা স্ট্রিং path-এর পরের newline-এ শেষ হয়

যাচাই করতে:

  1. কোনো parsing-এর আগে header, method, raw path ও query, এবং raw body পড়ুন।
  2. header থেকে t এবং প্রতিটি v1 নিন।
  3. t আপনার ঘড়ির সময়ের আগে বা পরে 300 সেকেন্ডের বেশি হলে অনুরোধটি প্রত্যাখ্যান করুন।
  4. আপনার secret দিয়ে সাইন করা স্ট্রিংয়ের hex HMAC-SHA256 গণনা করুন।
  5. v1-এর সঙ্গে constant time-এ তুলনা করুন। কিছুই না মিললে 401 পাঠান।

কার্যকর উদাহরণ

Secret whsec_example_4c1f2a9b। আমরা এই অনুরোধটি পাঠাই t = 1767225600 (2026-01-01 00:00:00 UTC)-এ:

POST /tools/lookup?region=us HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-ThunderPhone-Signature-V2: t=1767225600,v1=03a89bec521f78d55727237ca4713bb0b8dcdf2e09e450865b5b5637b80c1c4e
 
{"customer_id":"cust_123"}

সাইন করা স্ট্রিংটি এই চারটি লাইন, body-এর পরে কোনো newline ছাড়া:

1767225600
POST
/tools/lookup?region=us
{"customer_id":"cust_123"}

এর HMAC-SHA256 হলো 03a89bec521f78d55727237ca4713bb0b8dcdf2e09e450865b5b5637b80c1c4e। এর বিপরীতে আপনার implementation যাচাই করুন, অথবা openssl দিয়ে পুনরুৎপাদন করুন:

printf '1767225600\nPOST\n/tools/lookup?region=us\n{"customer_id":"cust_123"}' \
  | openssl dgst -sha256 -hmac 'whsec_example_4c1f2a9b'

একই সেকেন্ডে /tools/lookup?customer_id=cust_123-এ একটি GET tool call-এর body খালি থাকে। এর সাইন করা স্ট্রিং হলো 1767225600\nGET\n/tools/lookup?customer_id=cust_123\n এবং এর সিগনেচার হলো 3ce214cb0b8f2bf39b1d19d4e7265df9dbaff5a5f838d3cc6c753a8f7a4ad280।

SDK-সহ

Python এবং TypeScript SDK-তে একটি helper অন্তর্ভুক্ত আছে (thunderphone 0.2.0 বা পরবর্তী, @thunderphone/sdk 0.2.0 বা পরবর্তী)। এটি 5-মিনিটের window পরীক্ষা করে, constant time-এ তুলনা করে এবং secret-এর একটি তালিকা গ্রহণ করে, যাতে আপনি downtime ছাড়াই rotate করতে পারেন।

Python
from thunderphone import verify_signature
 
ok = verify_signature(
    header,            # the X-ThunderPhone-Signature-V2 value
    secret=SECRET,     # or [NEW_SECRET, OLD_SECRET] while rotating
    method=method,     # "POST"
    path=path,         # "/tools/lookup?region=us", exactly as received
    body=raw_body,     # bytes, before any JSON parsing
    tolerance=300,     # optional; seconds
)
Node.js
import { verifySignature } from "@thunderphone/sdk";
 
const ok = verifySignature({
  header,               // the X-ThunderPhone-Signature-V2 value
  secret: SECRET,       // or [NEW_SECRET, OLD_SECRET] while rotating
  method,               // "POST"
  path,                 // "/tools/lookup?region=us", exactly as received
  body: rawBody,        // Buffer or string, before any JSON parsing
  toleranceSeconds: 300, // optional
});

SDK ছাড়া

Python
import hashlib
import hmac
import time
 
TOLERANCE_SECONDS = 300
 
 
def verify_v2(header: str, secret: str, method: str, path: str, body: bytes) -> bool:
    """path is the path plus ?query exactly as received; body is the raw body."""
    timestamp, signatures = None, []
    for item in (header or "").split(","):
        key, _, value = item.strip().partition("=")
        if key == "t" and value.isdigit() and len(value) <= 15:
            timestamp = int(value)
        elif key == "v1":
            signatures.append(value)
    if timestamp is None or abs(time.time() - timestamp) > TOLERANCE_SECONDS:
        return False
    signed = f"{timestamp}\n{method.upper()}\n{path}\n".encode() + body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected.encode(), s.encode()) for s in signatures)
Node.js
import crypto from "node:crypto";
 
const TOLERANCE_SECONDS = 300;
 
// path is the path plus ?query exactly as received; body is the raw Buffer.
export function verifyV2(header, secret, method, path, body) {
  let timestamp;
  const signatures = [];
  for (const item of (header || "").split(",")) {
    const [key, value = ""] = item.trim().split("=", 2);
    if (key === "t" && /^\d+$/.test(value)) timestamp = Number(value);
    else if (key === "v1") signatures.push(value);
  }
  if (timestamp === undefined) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) return false;
  const expected = Buffer.from(
    crypto
      .createHmac("sha256", secret)
      .update(`${timestamp}\n${method.toUpperCase()}\n${path}\n`)
      .update(body)
      .digest("hex"),
  );
  return signatures.some((sig) => {
    const candidate = Buffer.from(sig);
    return (
      candidate.length === expected.length &&
      crypto.timingSafeEqual(candidate, expected)
    );
  });
}

ফ্রেমওয়ার্ক সংযোগ

প্রতিটি উদাহরণ raw path ও query এবং raw body পড়ে, তারপর SDK helper কল করে।

FastAPI
import json
 
from fastapi import FastAPI, HTTPException, Request
from thunderphone import verify_signature
 
app = FastAPI()
 
 
def raw_path_and_query(request: Request) -> str:
    path = (request.scope.get("raw_path") or request.url.path.encode()).decode("latin-1")
    query = request.scope.get("query_string", b"").decode("latin-1")
    return f"{path}?{query}" if query else path
 
 
@app.post("/thunderphone-webhook")
async def hook(request: Request):
    body = await request.body()  # raw bytes, NOT request.json()
    if not verify_signature(
        request.headers.get("X-ThunderPhone-Signature-V2"),
        secret=SECRET,
        method=request.method,
        path=raw_path_and_query(request),
        body=body,
    ):
        raise HTTPException(status_code=401)
    event = json.loads(body)
    # … dispatch on event["type"] …
    return {"ok": True}
Express
import express from "express";
import { verifySignature } from "@thunderphone/sdk";
 
const app = express();
 
app.post(
  "/thunderphone-webhook",
  // IMPORTANT: parse as raw; do NOT use express.json() here.
  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, // path and query as received
      body: req.body,
    });
    if (!ok) return res.sendStatus(401);
    const event = JSON.parse(req.body.toString("utf8"));
    // … dispatch on event.type …
    res.sendStatus(204);
  },
);
Django
import json
 
from django.http import HttpResponseForbidden, JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST
from thunderphone import verify_signature
 
 
@csrf_exempt
@require_POST
def hook(request):
    if not verify_signature(
        request.headers.get("X-ThunderPhone-Signature-V2"),
        secret=SECRET,
        method=request.method,
        path=request.get_full_path(),
        body=request.body,  # raw bytes
    ):
        return HttpResponseForbidden("invalid signature")
    event = json.loads(request.body)
    # … dispatch on event["type"] …
    return JsonResponse({"ok": True})

req.originalUrl (Express) এবং ASGI-এর raw_path ও query_string (FastAPI) প্রাপ্ত অবস্থার target-এর সঙ্গে হুবহু মিলে যায়। Django-এর get_full_path() এবং Flask-এর request.path প্রথমে path decode করে, যা সাধারণ path-এর ক্ষেত্রে একই string দেয়। আপনার endpoint path-এ যদি %2F, ; বা =-এর মতো percent-encoded বা reserved character থাকে, তাহলে তার পরিবর্তে আপনার server যে raw target দেয় তা পড়ুন (উদাহরণস্বরূপ, Gunicorn-এ request.META["RAW_URI"])।

কোন সিক্রেট?

একই secret উভয় header-এ স্বাক্ষর করে।

উৎসসিক্রেট
Webhook এন্ডপয়েন্ট (/v1/developer/webhook-endpoints)তৈরির সময় একবার ফেরত দেওয়া প্রতি-এন্ডপয়েন্ট secret (48 হেক্স অক্ষর)
লিগ্যাসি একক-URL webhookGET /v1/webhook-এ ফেরত দেওয়া প্রতি-অর্গ secret
টুল-এন্ডপয়েন্ট ইনভোকেশন (আপনার endpoint.url-এ সরাসরি কল)অর্গ-স্তরের webhook সিক্রেট (লিগ্যাসি একক-URL webhook-এর একইটি) — প্রতি-এন্ডপয়েন্ট সিক্রেট নয়

সিক্রেটটি আপনার সিক্রেট ম্যানেজার বা env var-এ সংরক্ষণ করুন — কখনো কমিট করবেন না।

টুল কল যাচাই করা

এজেন্ট যখন আপনার কোনো ফাংশন টুল সরাসরি আহ্বান করে (টুলটির একটি endpoint থাকে), তখন অনুরোধটি আপনার কনফিগার করা endpoint.headers-এর সঙ্গে এই ThunderPhone হেডারগুলো বহন করে:

  • X-ThunderPhone-Call-ID — চলমান কলের সংখ্যাসূচক আইডি।
  • X-ThunderPhone-Signature-V2 — উপরের টাইমস্ট্যাম্পযুক্ত স্বাক্ষর, আপনার সংস্থা-স্তরের ওয়েবহুক সিক্রেট দিয়ে কী করা।
  • X-ThunderPhone-Signature — পুরোনো শুধু-বডি স্বাক্ষর, একই কী।

ফোন কলগুলিতে X-ThunderPhone-From-Number, X-ThunderPhone-To-Number এবং X-ThunderPhone-Call-Directionও থাকে (বিস্তারিত)। প্রতিটি হেডারের মতো, এগুলিও কোনো সিগনেচারের আওতাভুক্ত নয়।

আপনার org কখনও লিগ্যাসি webhook কনফিগার না করলেও প্রতিটি টুল রিকোয়েস্ট সই করা হয়: ThunderPhone স্বয়ংক্রিয়ভাবে org secret তৈরি করে। এটি GET /v1/webhook থেকে পড়ুন।

webhook-এর থেকে একটি বিষয় ভিন্ন: GET / DELETE টুলের কোনো body নেই। আর্গুমেন্টগুলো query parameter হিসেবে পাঠানো হয়। V2 সিগনেচার path ও query-এর মাধ্যমে সেগুলো অন্তর্ভুক্ত করে এবং body ফিল্ডটি খালি থাকে। raw query string দিয়ে যাচাই করুন: parameter পার্স করে নতুন query string তৈরি করলে তাদের ক্রম বা encoding পরিবর্তিত হতে পারে। লিগ্যাসি হেডারটি খালি byte string-এ সই করে।

@app.api_route("/tools/search-appointments", methods=["GET", "POST"])
async def tool(request: Request):
    body = await request.body()  # b"" for GET/DELETE tools
    if not verify_signature(
        request.headers.get("X-ThunderPhone-Signature-V2"),
        secret=ORG_WEBHOOK_SECRET,
        method=request.method,
        path=raw_path_and_query(request),
        body=body,
    ):
        raise HTTPException(status_code=401)
    call_id = request.headers.get("X-ThunderPhone-Call-ID", "")
    args = json.loads(body) if body else dict(request.query_params)
    ...

Express-এ, একটি বডি পার্সার GET অনুরোধে req.body-কে খালি অবজেক্ট হিসেবে রেখে দেয়, তাই Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0) পাঠান।

Webhook-মোডের টুল ডিসপ্যাচে (endpoint ছাড়া টুল, যা আপনার সংস্থার webhook-এ telephony.tool / web.tool হিসেবে পাঠানো হয়) এটি একটি সাধারণ স্বাক্ষরিত webhook — উপরের মানক পদ্ধতিটি প্রযোজ্য। উভয় অনুরোধের ধরন দেখতে ফাংশন টুল দেখুন।

লিগ্যাসি স্বাক্ষর: X-ThunderPhone-Signature

মূল হেডারটি শুধু raw body-এর হেক্স HMAC-SHA256, একই সিক্রেট ব্যবহার করে। এতে কোনো টাইমস্ট্যাম্প নেই, তাই স্বাক্ষরিত একটি রিকোয়েস্ট আটকাতে পারলে যে কেউ সেটি পুনরায় চালাতে পারে। ইন্টিগ্রেশনগুলো V2-তে স্থানান্তরিত হওয়ার সময়ও এটি প্রতিটি রিকোয়েস্টে পাঠানো হয়।

  1. raw রিকোয়েস্ট body পড়ুন — আমরা আপনাকে যে হুবহু বাইট পাঠিয়েছি।
  2. hmac_sha256(secret, body).hexdigest() গণনা করুন।
  3. X-ThunderPhone-Signature-এর সঙ্গে ধ্রুব সময়ে তুলনা করুন।

আমরা যে বাইটগুলো পাঠাই, ঠিক সেগুলোতেই স্বাক্ষর করি। এই বাইটগুলো payload-এর ক্যানোনিক্যাল JSON সিরিয়ালাইজেশনও — কীগুলো বর্ণানুক্রমে সাজানো, কমপ্যাক্ট সেপারেটর (কোনো স্পেস ছাড়া , এবং :), UTF-8। আপনার ফ্রেমওয়ার্ক যদি শুধু পার্স করা JSON প্রকাশ করে, তাহলে সেটিকে ক্যানোনিক্যালভাবে পুনরায় সিরিয়ালাইজ করুন এবং তার HMAC গণনা করুন:

# Equivalent to hashing the raw body:
import json
canonical = json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8")

raw body অগ্রাধিকার দিন — এতে একটি ধাপ কম লাগে এবং কিছু ভাষায় JSON সংখ্যার রাউন্ড-ট্রিপিংজনিত অদ্ভুত আচরণ থেকে সুরক্ষিত থাকে। V2-এর body ফিল্ডের ক্ষেত্রেও একই কথা প্রযোজ্য।

Python
import hashlib
import hmac
 
 
def verify(body: bytes, signature: str, secret: str) -> bool:
    """Constant-time HMAC-SHA256 verification."""
    expected = hmac.new(
        secret.encode("utf-8"),
        body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature or "")
Node.js
import crypto from "node:crypto";
 
export function verify(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),
  );
}
Go
package webhook
 
import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)
 
func Verify(body []byte, signature, secret string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(signature))
}
Ruby
require "openssl"
 
def verify(body, signature, secret)
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, body)
  Rack::Utils.secure_compare(expected, signature.to_s)
end

সাধারণ সমস্যাসমূহ

ঘড়ির সময়ের বিচ্যুতি

5-মিনিটের সময়সীমা আপনার সার্ভারের ঘড়ির বিপরীতে মাপা হয়। এটিকে NTP-এর সঙ্গে সিঙ্ক্রোনাইজ রাখুন; 5 মিনিটের বেশি সময়ের ব্যবধান থাকা ঘড়ি প্রতিটি অনুরোধ প্রত্যাখ্যান করে।

একটি প্রক্সি পাথ পুনর্লিখন করে

স্বাক্ষরিত পাথটি আমরা যে পাথের অনুরোধ করেছি সেটিই: ThunderPhone-এ আপনি কনফিগার করা URL-এর পাথ। আপনার অ্যাপ্লিকেশন অনুরোধটি দেখার আগে যদি একটি রিভার্স প্রক্সি বা API গেটওয়ে কোনো প্রিফিক্স সরিয়ে দেয় বা যোগ করে, তাহলে যাচাই করার আগে আমাদের পাঠানো পাথটি পুনর্গঠন করুন (উদাহরণস্বরূপ, প্রিফিক্সটি আবার যোগ করুন)।

ডিফল্ট ফরম্যাটিং দিয়ে পুনরায় সিরিয়ালাইজ করা

বডি পার্স করে আপনার JSON লাইব্রেরির ডিফল্ট সেটিংস দিয়ে আবার ডাম্প করলে (, / :-এর পরে স্পেস, ইনসার্শন-অর্ডার করা কী) ভিন্ন বাইট তৈরি হয় এবং HMAC ভেঙে যায়। কাঁচা বডি যাচাই করুন — অথবা যদি আপনাকে পুনরায় সিরিয়ালাইজ করতেই হয়, আমাদের ক্যানোনিক্যাল ফর্মের সঙ্গে হুবহু মিল রাখুন: সাজানো কী, কমপ্যাক্ট সেপারেটর, UTF-8।

ফ্রেমওয়ার্ক স্বয়ংক্রিয়ভাবে JSON পার্স করে

Express-এর express.json() মিডলওয়্যার বডি স্ট্রিম ব্যবহার করে ফেলে এবং আপনি কাঁচা বাইট হারান। ওয়েবহুক রুটে নির্দিষ্টভাবে express.raw() ব্যবহার করুন, অথবা প্রি-মিডলওয়্যারে কাঁচা বডি বাফার করুন। NestJS / Koa-এর ক্ষেত্রেও একই বিষয় — তাদের "কাঁচা বডি" ডকুমেন্টেশন দেখুন।

টাইমিং-অনিরাপদ তুলনা

JS-এ expected === signature অথবা Python-এ expected == signature টাইমিং-ভেরিয়েবল তুলনা। যথাক্রমে crypto.timingSafeEqual অথবা hmac.compare_digest ব্যবহার করুন। পারফরম্যান্সের পার্থক্য নেই।

টুল এন্ডপয়েন্টের জন্য ভুল সিক্রেট

সরাসরি টুল-এন্ডপয়েন্ট কলগুলো প্রতিষ্ঠান-স্তরের ওয়েবহুক সিক্রেট (GET /v1/webhook) দিয়ে স্বাক্ষরিত হয় — /v1/developer/webhook-endpoints-এর কোনো এন্ডপয়েন্ট-প্রতি সিক্রেট দিয়ে নয়। একই হেল্পার পুনর্ব্যবহার করুন, তবে নিশ্চিত করুন যে টুল রুটে আপনি এটিকে প্রতিষ্ঠানের সিক্রেট দিচ্ছেন।

GET/DELETE টুলে কোয়েরি স্ট্রিং

V2 ঠিক যেভাবে পাঠানো হয়েছে সেভাবেই কোয়েরি স্ট্রিং স্বাক্ষর করে। লিগ্যাসি হেডার খালি বডি স্বাক্ষর করে এবং কখনোই কোয়েরি স্ট্রিং নয়, তাই লিগ্যাসি হেডারের জন্য URL হ্যাশ করলে তা কখনোই মিলবে না।

সময়সীমার মধ্যে ডুপ্লিকেট

টাইমস্ট্যাম্প 5 মিনিটের বেশি পুরোনো রিপ্লে বন্ধ করে, কিন্তু সেই সময়সীমার মধ্যে থাকা দ্বিতীয় কপিকে নয়। এন্ডপয়েন্ট ডেলিভারি অন্তত একবার নিশ্চিত করা হয়, তাই একই ইভেন্টের একটি পুনঃচেষ্টাও আসতে পারে; এনভেলপের event_id দিয়ে ডুপ্লিকেট বাদ দিন।

অমিল হলে 401 ফেরত না দেওয়া

যাচাইকরণ ব্যর্থ হলে 200 ফেরত দিলে হ্যান্ডলারটি রিপ্লে টার্গেটে পরিণত হয়। যাচাইকরণ ব্যর্থ হলে সর্বদা নন-2xx রেসপন্স দিন।


পরবর্তী ধাপ