ThunderPhone v3 sasa inapatikana.Anza mwenyewe, kuanzia 2¢/dakika.Soma tangazo

Operations

Thibitisha sahihi za webhook

Kila ombi la webhook na zana linalotumwa na ThunderPhone hutiwa sahihi pamoja na muhuri wa wakati. Lithibitishe kwa kutumia recipe au msaidizi wa SDK hapa, na ukatae maombi yaliyotumwa tena yaliyozidi dakika tano.

Kila ombi tunalotuma kwa seva yako (uwasilishaji wa webhook, webhook ya zamani ya URL moja na miito ya endpoint ya zana) hubeba vichwa viwili vya sahihi. Vyote ni HMAC-SHA256 yenye siri moja.

KichwaHusainiUlinzi dhidi ya kurudia
X-ThunderPhone-Signature-V2 (inapendekezwa)Muhuri wa muda, mbinu, njia, query na mwiliKataa maombi yaliyo zaidi ya dakika 5
X-ThunderPhone-SignatureMwili pekeeHakuna: ombi lililonaswa linathibitishwa milele

Thibitisha X-ThunderPhone-Signature-V2 katika miunganisho mipya na hamishia zilizopo kwake. X-ThunderPhone-Signature bado hutumwa kwenye kila ombi, bila kubadilishwa, kwa hivyo vithibitishaji vilivyojengwa juu yake vinaendelea kufanya kazi. Tutatangaza tarehe kabla ya kuacha kuituma.

Sahihi V2

X-ThunderPhone-Signature-V2: t=1767225600,v1=03a89bec521f78d55727237ca4713bb0b8dcdf2e09e450865b5b5637b80c1c4e
  • t ni muda wa Unix, kwa sekunde, tulipotuma ombi. Uwasilishaji unaojaribiwa tena husainiwa upya unapopelekwa, ukiwa na t yake mwenyewe.
  • v1 ni HMAC-SHA256 ya heksadesimali ya mfuatano uliosainiwa hapa chini, unaotumia siri yako kama ufunguo.

Thamani ni orodha ya jozi za key=value zilizotenganishwa kwa koma. Puuza funguo usizotambua, na ukubali ombi ikiwa v1 yoyote inalingana: tunaweza kuongeza sahihi ya pili wakati wa mabadiliko yajayo.

Mfuatano uliosainiwa

Sehemu nne, kila moja ikifuatwa na mstari mpya (\n, baiti 0x0A) isipokuwa ya mwisho:

<t>\n<METHOD>\n<path and query>\n<body>
SehemuThamani
tThamani ya t kutoka kwenye kichwa
METHODMbinu ya HTTP kwa herufi kubwa: POST, GET, PUT, PATCH au DELETE
path and queryLengo la ombi kutoka mstari wa ombi wa HTTP: njia, kisha ? na mfuatano wa hoja inapokuwepo. Bila mpangilio, hosti au kipande. Itumie jinsi ilivyowasili, bila kuisimbua au kupanga upya vigezo
bodyMwili ghafi wa ombi. Miito ya zana ya GET na DELETE haina mwili, kwa hivyo mfuatano wake uliosainiwa huisha kwa mstari mpya baada ya njia

Ili kuthibitisha:

  1. Kabla ya uchanganuzi wowote, soma kichwa, mbinu, njia ghafi na hoja, pamoja na mwili ghafi.
  2. Chukua t na kila v1 kutoka kwenye kichwa.
  3. Kataa ombi ikiwa t iko zaidi ya sekunde 300 kabla au baada ya saa yako.
  4. Kokotoa HMAC-SHA256 ya heksadesimali ya mfuatano uliosainiwa kwa siri yako.
  5. Ilinganishe na v1 kwa muda usiobadilika. Jibu 401 ikiwa hakuna kinacholingana.

Mfano uliofanyiwa kazi

Siri whsec_example_4c1f2a9b. Tunatuma ombi hili saa 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"}

Mfuatano uliosainiwa ni mistari hii minne, bila mstari mpya baada ya mwili:

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

HMAC-SHA256 yake ni 03a89bec521f78d55727237ca4713bb0b8dcdf2e09e450865b5b5637b80c1c4e. Kagua utekelezaji wako ukitumia thamani hiyo, au uizalishe kwa openssl:

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

Mwito wa zana wa GET kwenda /tools/lookup?customer_id=cust_123 katika sekunde hiyo hiyo una mwili tupu. Mfuatano wake uliosainiwa ni 1767225600\nGET\n/tools/lookup?customer_id=cust_123\n na sahihi yake ni 3ce214cb0b8f2bf39b1d19d4e7265df9dbaff5a5f838d3cc6c753a8f7a4ad280.

Kwa SDK

SDK za Python na TypeScript zinajumuisha kisaidizi (thunderphone 0.2.0 au mpya zaidi, @thunderphone/sdk 0.2.0 au mpya zaidi). Hukagua dirisha la dakika 5, hulinganisha kwa muda usiobadilika, na hukubali orodha ya siri ili uweze kubadilisha bila muda wa kutopatikana.

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
});

Bila 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)
    );
  });
}

Muunganisho wa framework

Kila mfano husoma njia ghafi na query, pamoja na body ghafi, kisha kuita msaidizi wa 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) na raw_path pamoja na query_string za ASGI (FastAPI) ni lengwa haswa jinsi zilivyopokelewa. get_full_path() ya Django na request.path ya Flask hufumbua njia kwanza, jambo linalotoa string ileile kwa njia za kawaida. Ikiwa njia ya endpoint yako ina herufi zilizosimbwa kwa asilimia au herufi zilizohifadhiwa kama %2F, ; au =, soma badala yake lengwa ghafi linalotolewa na seva yako (kwa mfano request.META["RAW_URI"] kwenye Gunicorn).

Siri ipi?

Siri hiyo hiyo hutia sahihi vichwa vyote viwili.

ChanzoSiri
Endpoint ya webhook (/v1/developer/webhook-endpoints)secret ya kila endpoint (herufi 48 za heksadesimali) inayorejeshwa mara moja wakati wa kuunda
Webhook ya zamani ya URL mojasecret ya kila shirika inayorejeshwa kwenye GET /v1/webhook
Uitishaji wa endpoint ya zana (mwito wa moja kwa moja kwa endpoint.url yako)Siri ya webhook ya kiwango cha shirika (sawa na ile ya webhook ya zamani ya URL moja) — si siri ya kila endpoint

Hifadhi siri katika kidhibiti chako cha siri au kigeu cha mazingira — usiiweke kamwe kwenye commit.

Kuthibitisha miito ya zana

Wakati ejenti inapoitisha moja kwa moja mojawapo ya zana zako za utendaji (zana ina endpoint), ombi hubeba header hizi za ThunderPhone pamoja na endpoint.headers ulizosanidi:

  • X-ThunderPhone-Call-ID — kitambulisho cha nambari cha simu inayoendelea.
  • X-ThunderPhone-Signature-V2 — sahihi iliyo na muhuri wa muda hapo juu, inayotumia siri ya webhook ya kiwango cha shirika.
  • X-ThunderPhone-Signature — sahihi ya zamani ya mwili pekee, yenye ufunguo huo huo.

Simu pia hubeba X-ThunderPhone-From-Number, X-ThunderPhone-To-Number na X-ThunderPhone-Call-Direction (maelezo). Kama kila header, hazijajumuishwa na sahihi yoyote kati ya hizo.

Kila ombi la zana hutiwa sahihi, hata kama org yako haijawahi kusanidi webhook ya urithi: ThunderPhone huunda secret ya org kiotomatiki. Isome kutoka GET /v1/webhook.

Jambo moja hutofautiana na webhook: zana za GET / DELETE hazina body. Hoja hupitishwa kama query parameters. Sahihi ya V2 huzijumuisha kupitia path na query, na sehemu ya body huwa tupu. Thibitisha kwa raw query string: kuchanganua parameters na kuunda query string mpya kunaweza kubadilisha mpangilio au encoding yake. Header ya urithi hutia sahihi byte string tupu.

@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)
    ...

Katika Express, kichanganuzi cha mwili huacha req.body kama kitu tupu kwenye GET, kwa hiyo pitisha Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0).

Usambazaji wa zana katika hali ya webhook (zana zisizo na endpoint, zinazoletwa kwenye webhook ya shirika lako kama telephony.tool / web.tool) ni webhook ya kawaida iliyotiwa sahihi — utaratibu wa kawaida hapo juu unatumika. Tazama Zana za Function kwa miundo yote miwili ya ombi.

Sahihi ya zamani: X-ThunderPhone-Signature

Kijajuu cha awali ni HMAC-SHA256 ya hex ya raw body pekee, kwa kutumia siri ileile. Hakina timestamp, kwa hivyo mtu yeyote anayenasa ombi moja lililotiwa sahihi anaweza kulirudia. Bado hutumwa kwenye kila ombi huku integrations zikihamia V2.

  1. Soma mwili mbichi wa ombi — byte kamili tulizokutumia.
  2. Hesabu hmac_sha256(secret, body).hexdigest().
  3. Linganisha kwa muda usiobadilika na X-ThunderPhone-Signature.

Tunatia sahihi byte zilezile tunazotuma. Byte hizo pia ni usawazishaji wa JSON wa kanoni wa payload — funguo zimepangwa kialfabeti, vitenganishi vifupi (, na : bila nafasi), UTF-8. Ikiwa framework yako hutoa JSON iliyochanganuliwa pekee, isawazishe tena kwa kanoni na ufanye HMAC kwa hiyo:

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

Pendelea raw body — ni hatua moja pungufu na hailengiwi na hitilafu za kubadilisha namba za JSON kwenda na kurudi katika baadhi ya lugha. Hali hiyo hiyo inatumika kwa sehemu ya body ya 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

Changamoto za kawaida

Tofauti ya saa

Dirisha la dakika 5 hupimwa kulingana na saa ya seva yako. Iweke ikisawazishwa na NTP; saa iliyopotoka kwa zaidi ya dakika 5 hukataa kila ombi.

Proksi huandika upya njia

Njia iliyotiwa sahihi ni ile tuliyoomba: njia ya URL uliyosanidi katika ThunderPhone. Ikiwa proksi ya nyuma au lango la API huondoa au huongeza kiambishi kabla programu yako haijaona ombi, unda upya njia tuliyotuma (kwa mfano, rudisha kiambishi) kabla ya kuthibitisha.

Kusajili upya kwa uumbizaji chaguo-msingi

Kuchanganua mwili na kuutoa tena kwa chaguo-msingi za maktaba yako ya JSON (nafasi baada ya , / :, funguo zilizopangwa kwa mpangilio wa uingizaji) huzalisha baiti tofauti na huharibu HMAC. Thibitisha mwili ghafi — au ikiwa ni lazima usajili upya, linganisha kabisa na umbo letu kanoniki: funguo zilizopangwa, vitenganishi finyu, UTF-8.

Framework huchanganua JSON kiotomatiki

Middleware ya express.json() ya Express hutumia mtiririko wa mwili na unapoteza baiti ghafi. Tumia express.raw() mahsusi kwenye njia ya webhook, au hifadhi mwili ghafi kwenye pre-middleware. Hali ni sawa kwa NestJS / Koa — angalia nyaraka zao za "raw body".

Ulinganisho usio salama kwa muda

expected === signature katika JS au expected == signature katika Python ni ulinganisho unaobadilika kulingana na muda. Tumia crypto.timingSafeEqual au hmac.compare_digest mtawalia. Tofauti ya utendaji haipo.

Siri isiyo sahihi kwa endpoint za zana

Miito ya moja kwa moja kwa endpoint za zana hutiwa sahihi kwa siri ya webhook ya kiwango cha shirika (GET /v1/webhook) — si kwa siri yoyote ya kila endpoint kutoka /v1/developer/webhook-endpoints. Tumia tena kisaidizi hichohicho, lakini hakikisha unakipa siri ya shirika kwenye njia za zana.

Mifuatano ya hoja kwenye zana za GET/DELETE

V2 hutia sahihi mfuatano wa hoja kama ulivyotumwa. Kijajuu cha urithi hutia sahihi mwili tupu na kamwe si mfuatano wa hoja, kwa hivyo kuhesabu heshi ya URL kwa kijajuu cha urithi hakutawahi kulingana.

Nakala rudufu ndani ya dirisha

Muhuri wa muda huzuia urudishaji wa ombi uliozidi dakika 5, si nakala ya pili ndani ya dirisha hilo. Uwasilishaji wa endpoint hufanyika angalau mara moja, kwa hivyo jaribio upya la tukio lilelile linaweza pia kuwasili; ondoa nakala rudufu kwa kutumia event_id ya bahasha.

Kutorejesha 401 kunapokuwa na kutolingana

Kurejesha 200 uthibitishaji unaposhindwa hufanya kishughulikiaji kuwa lengo la mashambulizi ya kurudia ombi. Daima jibu kwa hali isiyo ya 2xx uthibitishaji unaposhindwa.


Hatua zinazofuata