Open in
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.
| Kichwa | Husaini | Ulinzi dhidi ya kurudia |
|---|---|---|
X-ThunderPhone-Signature-V2 (inapendekezwa) | Muhuri wa muda, mbinu, njia, query na mwili | Kataa maombi yaliyo zaidi ya dakika 5 |
X-ThunderPhone-Signature | Mwili pekee | Hakuna: 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=03a89bec521f78d55727237ca4713bb0b8dcdf2e09e450865b5b5637b80c1c4etni muda wa Unix, kwa sekunde, tulipotuma ombi. Uwasilishaji unaojaribiwa tena husainiwa upya unapopelekwa, ukiwa natyake mwenyewe.v1ni 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>| Sehemu | Thamani |
|---|---|
t | Thamani ya t kutoka kwenye kichwa |
METHOD | Mbinu ya HTTP kwa herufi kubwa: POST, GET, PUT, PATCH au DELETE |
| path and query | Lengo 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 |
body | Mwili 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:
- Kabla ya uchanganuzi wowote, soma kichwa, mbinu, njia ghafi na hoja, pamoja na mwili ghafi.
- Chukua
tna kilav1kutoka kwenye kichwa. - Kataa ombi ikiwa
tiko zaidi ya sekunde 300 kabla au baada ya saa yako. - Kokotoa HMAC-SHA256 ya heksadesimali ya mfuatano uliosainiwa kwa siri yako.
- Ilinganishe na
v1kwa muda usiobadilika. Jibu401ikiwa 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.
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
)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
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)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.
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}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);
},
);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.
| Chanzo | Siri |
|---|---|
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 moja | secret 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.
- Soma mwili mbichi wa ombi — byte kamili tulizokutumia.
- Hesabu
hmac_sha256(secret, body).hexdigest(). - 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.
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 "")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),
);
}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))
}require "openssl"
def verify(body, signature, secret)
expected = OpenSSL::HMAC.hexdigest("SHA256", secret, body)
Rack::Utils.secure_compare(expected, signature.to_s)
endChangamoto 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.