ThunderPhone v3 ഇപ്പോൾ ലൈവാണ്.സ്വയം തുടങ്ങാം — 2¢/മിനിറ്റ് മുതൽ.പ്രഖ്യാപനം വായിക്കുക

Operations

വെബ്ഹുക്ക് സിഗ്നേച്ചറുകൾ പരിശോധിക്കുക

ThunderPhone അയയ്ക്കുന്ന ഓരോ വെബ്ഹുക്കും ടൂൾ അഭ്യർത്ഥനയും ടൈംസ്റ്റാമ്പോടെ സൈൻ ചെയ്തതാണ്. ഇവിടെ നൽകിയിരിക്കുന്ന റെസിപ്പിയോ SDK ഹെൽപ്പറോ ഉപയോഗിച്ച് അത് പരിശോധിച്ച്, അഞ്ച് മിനിറ്റിൽ കൂടുതൽ പഴക്കമുള്ള വീണ്ടും അയച്ച അഭ്യർത്ഥനകൾ നിരസിക്കുക.

നിങ്ങളുടെ സെർവറിലേക്ക് ഞങ്ങൾ അയയ്ക്കുന്ന ഓരോ അഭ്യർത്ഥനയിലും (വെബ്ഹുക്ക് ഡെലിവറികൾ, ലെഗസി ഒറ്റ-URL വെബ്ഹുക്ക്, ടൂൾ-എൻഡ്പോയിന്റ് കോളുകൾ) രണ്ട് സിഗ്നേച്ചർ ഹെഡറുകൾ ഉൾപ്പെടുന്നു. രണ്ടും ഒരേ സീക്രട്ട് ഉപയോഗിച്ചുള്ള HMAC-SHA256 ആണ്.

ഹെഡർഒപ്പിടുന്നത്റീപ്ലേ സംരക്ഷണം
X-ThunderPhone-Signature-V2 (ശുപാർശ ചെയ്യുന്നത്)ടൈംസ്റ്റാമ്പ്, മെത്തഡ്, പാത്ത്, ക്വറി, ബോഡി5 മിനിറ്റിൽ കൂടുതൽ പഴക്കമുള്ള അഭ്യർത്ഥനകൾ നിരസിക്കുക
X-ThunderPhone-Signatureബോഡി മാത്രംഒന്നുമില്ല: പിടിച്ചെടുത്ത ഒരു അഭ്യർത്ഥന എല്ലായ്പ്പോഴും പരിശോധിച്ചുറപ്പിക്കപ്പെടും

പുതിയ ഇന്റഗ്രേഷനുകളിൽ X-ThunderPhone-Signature-V2 പരിശോധിച്ച്, നിലവിലുള്ളവ അതിലേക്ക് മാറ്റുക. X-ThunderPhone-Signature ഇപ്പോഴും എല്ലാ അഭ്യർത്ഥനകളിലും മാറ്റമില്ലാതെ അയയ്ക്കപ്പെടുന്നു, അതിനാൽ അതിനെ അടിസ്ഥാനമാക്കി നിർമിച്ച വെരിഫയറുകൾ പ്രവർത്തിച്ചുകൊണ്ടിരിക്കും. ഇത് അയയ്ക്കുന്നത് നിർത്തുന്നതിന് മുമ്പ് ഞങ്ങൾ ഒരു തീയതി പ്രഖ്യാപിക്കും.

ഒപ്പ് V2

X-ThunderPhone-Signature-V2: t=1767225600,v1=03a89bec521f78d55727237ca4713bb0b8dcdf2e09e450865b5b5637b80c1c4e
  • ഞങ്ങൾ അഭ്യർത്ഥന അയച്ച സമയത്തെ സെക്കൻഡുകളിലുള്ള Unix സമയമാണ് t. വീണ്ടും ശ്രമിക്കുന്ന ഡെലിവറി അയയ്ക്കുമ്പോൾ, അതിന്റേതായ t ഉപയോഗിച്ച് അത് വീണ്ടും ഒപ്പിടപ്പെടും.
  • നിങ്ങളുടെ secret ഉപയോഗിച്ച് കീ ചെയ്ത, താഴെയുള്ള ഒപ്പിട്ട സ്ട്രിംഗിന്റെ hex HMAC-SHA256 ആണ് v1.

മൂല്യം കോമ ഉപയോഗിച്ച് വേർതിരിച്ച key=value ജോഡികളുടെ പട്ടികയാണ്. നിങ്ങൾ തിരിച്ചറിയാത്ത കീകൾ അവഗണിക്കുക, ഏതെങ്കിലും v1 പൊരുത്തപ്പെടുന്നുവെങ്കിൽ അഭ്യർത്ഥന സ്വീകരിക്കുക: ഭാവിയിലെ ഒരു മാറ്റത്തിനിടെ ഞങ്ങൾ രണ്ടാമത്തെ ഒപ്പ് ചേർത്തേക്കാം.

ഒപ്പിട്ട സ്ട്രിംഗ്

നാല് ഫീൽഡുകൾ; അവസാനത്തേത് ഒഴികെ ഓരോന്നിനും ശേഷം ഒരു newline (\n, byte 0x0A):

<t>\n<METHOD>\n<path and query>\n<body>
ഫീൽഡ്മൂല്യം
tഹെഡറിലെ t മൂല്യം
METHODവലിയ അക്ഷരങ്ങളിലുള്ള HTTP method: POST, GET, PUT, PATCH അല്ലെങ്കിൽ DELETE
path and queryHTTP request line-ൽ നിന്നുള്ള request target: path, തുടർന്ന് ?, കൂടാതെ ഉള്ളപ്പോൾ query string. scheme, host, fragment എന്നിവ ഇല്ല. ഡീകോഡ് ചെയ്യാതെയും parameters-ന്റെ ക്രമം മാറ്റാതെയും, ലഭിച്ചതുപോലെ തന്നെ ഉപയോഗിക്കുക
bodyഅസംസ്കൃത request body. GET, DELETE tool call-കൾക്ക് body ഇല്ല; അതിനാൽ അവയുടെ ഒപ്പിട്ട സ്ട്രിംഗ് path-നു ശേഷമുള്ള newline-ൽ അവസാനിക്കുന്നു

പരിശോധിക്കാൻ:

  1. parsing നടത്തുന്നതിന് മുമ്പ്, header, method, അസംസ്കൃത path, query, അസംസ്കൃത 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-ൽ താരതമ്യം ചെയ്യുകയും secrets-ന്റെ ഒരു പട്ടിക സ്വീകരിക്കുകയും ചെയ്യുന്നു, അതിനാൽ 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)
    );
  });
}

ഫ്രെയിംവർക്ക് കണക്ഷൻ

ഓരോ ഉദാഹരണവും റോ പാത്തും ക്വറിയും റോ ബോഡിയും വായിച്ച് SDK ഹെൽപ്പറിനെ വിളിക്കുന്നു.

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) എന്നിവ ലഭിച്ചതുപോലെ തന്നെയുള്ള ടാർഗറ്റാണ്. Django-യുടെ get_full_path() ഉം Flask-ന്റെ request.path ഉം ആദ്യം പാത്ത് ഡീകോഡ് ചെയ്യുന്നു; സാധാരണ പാത്തുകൾക്ക് ഇത് അതേ സ്ട്രിംഗ് നൽകും. നിങ്ങളുടെ എൻഡ്‌പോയിന്റ് പാത്തിൽ %2F, ;, അല്ലെങ്കിൽ = പോലുള്ള ശതമാനം-എൻകോഡ് ചെയ്തതോ റിസർവ് ചെയ്തതോ ആയ അക്ഷരങ്ങൾ ഉണ്ടെങ്കിൽ, പകരം നിങ്ങളുടെ സെർവർ നൽകുന്ന റോ ടാർഗറ്റ് വായിക്കുക (ഉദാഹരണത്തിന് Gunicorn-ൽ request.META["RAW_URI"]).

ഏത് secret?

ഒരേ രഹസ്യമാണ് രണ്ട് ഹെഡറുകളിലും ഒപ്പിടുന്നത്.

ഉറവിടംSecret
Webhook endpoint (/v1/developer/webhook-endpoints)സൃഷ്ടിക്കുമ്പോൾ ഒരിക്കൽ നൽകുന്ന ഓരോ endpoint-നുമുള്ള secret (48 hex chars)
Legacy single-URL webhookGET /v1/webhook-ൽ ലഭിക്കുന്ന ഓരോ org-നുമുള്ള secret
Tool-endpoint invocation (നിങ്ങളുടെ endpoint.url-ലേക്കുള്ള നേരിട്ടുള്ള കോൾ)org-level webhook secret (legacy single-URL webhook-ലേതിന് സമാനം) — endpoint-നുള്ള secret അല്ല

secret നിങ്ങളുടെ secret manager-ലോ env var-ലോ സൂക്ഷിക്കുക — ഒരിക്കലും commit ചെയ്യരുത്.

ടൂൾ കോളുകൾ പരിശോധിക്കൽ

ഏജന്റ് നിങ്ങളുടെ ഫംഗ്ഷൻ ടൂളുകളിലൊന്ന് നേരിട്ട് ഇൻവോക്ക് ചെയ്യുമ്പോൾ (ടൂളിന് ഒരു endpoint ഉണ്ട്), നിങ്ങളുടെ കോൺഫിഗർ ചെയ്ത endpoint.headers-നൊപ്പം റിക്വസ്റ്റിൽ ഈ ThunderPhone ഹെഡറുകൾ ഉണ്ടായിരിക്കും:

  • X-ThunderPhone-Call-ID — നിലവിലുള്ള കോളിന്റെ സംഖ്യാ ID.
  • X-ThunderPhone-Signature-V2 — നിങ്ങളുടെ ഓർഗനൈസേഷൻ-തല വെബ്ഹുക്ക് സീക്രട്ട് ഉപയോഗിച്ചുള്ള, മുകളിലെ ടൈംസ്റ്റാമ്പ് ഉൾപ്പെട്ട സിഗ്നേച്ചർ.
  • X-ThunderPhone-Signature — അതേ കീ ഉപയോഗിച്ചുള്ള ലെഗസി ബോഡി-മാത്രമുള്ള സിഗ്നേച്ചർ.

ഫോൺ കോളുകളിൽ X-ThunderPhone-From-Number, X-ThunderPhone-To-Number, X-ThunderPhone-Call-Direction എന്നിവയും ഉണ്ടായിരിക്കും (വിശദാംശങ്ങൾ). എല്ലാ ഹെഡറുകളെയും പോലെ, ഇവയും ഒരു സിഗ്നേച്ചറിലും ഉൾപ്പെടുന്നില്ല.

നിങ്ങളുടെ ഓർഗനൈസേഷൻ ലെഗസി വെബ്ഹുക്ക് ഒരിക്കലും കോൺഫിഗർ ചെയ്തിട്ടില്ലെങ്കിലും എല്ലാ ടൂൾ റിക്വസ്റ്റുകളിലും സിഗ്നേച്ചർ ഉണ്ടാകും: ThunderPhone ഓർഗനൈസേഷൻ സീക്രട്ട് സ്വയമേവ സൃഷ്ടിക്കുന്നു. അത് GET /v1/webhook-ൽ നിന്ന് വായിക്കുക.

വെബ്ഹുക്കുകളിൽ നിന്ന് ഒരു കാര്യം വ്യത്യസ്തമാണ്: GET / DELETE ടൂളുകൾക്ക് ബോഡി ഇല്ല. ആർഗ്യുമെന്റുകൾ ക്വറി പാരാമീറ്ററുകളായാണ് പോകുന്നത്. പാത്തിലൂടെയും ക്വറിയിലൂടെയും V2 സിഗ്നേച്ചർ അവയെ ഉൾക്കൊള്ളുന്നു, ബോഡി ഫീൽഡ് ശൂന്യമാണ്. റോ ക്വറി സ്ട്രിംഗ് ഉപയോഗിച്ച് പരിശോധിക്കുക: പാരാമീറ്ററുകൾ പാഴ്സ് ചെയ്ത് പുതിയ ക്വറി സ്ട്രിംഗ് നിർമിക്കുന്നത് അവയുടെ ക്രമമോ എൻകോഡിംഗോ മാറ്റാം. ലെഗസി ഹെഡർ ശൂന്യമായ ബൈറ്റ് സ്ട്രിംഗിലാണ് സൈൻ ചെയ്യുന്നത്.

@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) കൈമാറുക.

വെബ്ഹുക്ക്-മോഡ് ടൂൾ ഡിസ്പാച്ച് (endpoint ഇല്ലാത്തതും നിങ്ങളുടെ ഓർഗ് വെബ്ഹുക്കിലേക്ക് telephony.tool / web.tool ആയി എത്തുന്നതുമായ ടൂളുകൾ) ഒരു സാധാരണ സൈൻ ചെയ്ത വെബ്ഹുക്കാണ് — മുകളിലുള്ള സ്റ്റാൻഡേർഡ് രീതി ബാധകമാണ്. രണ്ട് റിക്വസ്റ്റ് രൂപങ്ങൾക്കും ഫംഗ്ഷൻ ടൂളുകൾ കാണുക.

ലെഗസി സിഗ്നേച്ചർ: X-ThunderPhone-Signature

ഒറിജിനൽ ഹെഡർ, അതേ സീക്രെറ്റ് ഉപയോഗിച്ചുള്ള റോ ബോഡിയുടെ മാത്രം ഹെക്സ് HMAC-SHA256 ആണ്. അതിൽ ടൈംസ്റ്റാമ്പ് ഇല്ല, അതിനാൽ ഒപ്പിട്ട ഒരു റിക്വസ്റ്റ് പിടിച്ചെടുക്കുന്ന ആർക്കും അത് റീപ്ലേ ചെയ്യാം. ഇന്റഗ്രേഷനുകൾ V2-ലേക്ക് മാറുമ്പോഴും എല്ലാ റിക്വസ്റ്റുകളിലും ഇത് അയക്കപ്പെടുന്നു.

  1. റോ റിക്വസ്റ്റ് ബോഡി വായിക്കുക — ഞങ്ങൾ നിങ്ങൾക്ക് അയച്ച കൃത്യമായ ബൈറ്റുകൾ.
  2. hmac_sha256(secret, body).hexdigest() കണക്കാക്കുക.
  3. X-ThunderPhone-Signature-നോട് സ്ഥിര സമയത്തിൽ താരതമ്യം ചെയ്യുക.

ഞങ്ങൾ കൈമാറുന്ന കൃത്യമായ ബൈറ്റുകളിലാണ് ഒപ്പിടുന്നത്. ആ ബൈറ്റുകൾ പേലോഡിന്റെ കാനോണിക്കൽ JSON സീരിയലൈസേഷനും ആണ് — കീകൾ അക്ഷരമാലാക്രമത്തിൽ ക്രമീകരിച്ചത്, കോംപാക്ട് സെപ്പറേറ്ററുകൾ (സ്പേസുകളില്ലാത്ത ,യും :യും), UTF-8. നിങ്ങളുടെ ഫ്രെയിംവർക്ക് പാർസ് ചെയ്ത JSON മാത്രം നൽകുന്നുവെങ്കിൽ, അത് കാനോണിക്കലായി വീണ്ടും സീരിയലൈസ് ചെയ്ത് അതിന് HMAC കണക്കാക്കുക:

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

റോ ബോഡി ഉപയോഗിക്കുന്നതാണ് ഉചിതം — അത് ഒരു ഘട്ടം കുറവാണ്, കൂടാതെ ചില ഭാഷകളിലെ JSON നമ്പർ റൗണ്ട്-ട്രിപ്പിംഗ് വ്യതിയാനങ്ങളിൽ നിന്ന് പ്രതിരോധമുള്ളതുമാണ്. V2-ന്റെ ബോഡി ഫീൽഡിനും ഇത് ബാധകമാണ്.

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-അല്ലാത്ത പ്രതികരണം നൽകുക.


അടുത്ത ഘട്ടങ്ങൾ