Skip to main content
Minden, az Ön szerverére küldött kérés — webhook-kézbesítés és eszközvégpont-meghívás — HMAC-SHA256-aláírást tartalmaz a X-ThunderPhone-Signature fejlécben. Állítsa be egyszer helyesen az ellenőrzést, majd használja ugyanazt a segédfüggvényt minden kezelőben.

Az algoritmus

  1. Olvassa be a nyers kérési törzset — pontosan azokat a bájtokat, amelyeket POST kéréssel küldtünk Önnek.
  2. Számítsa ki: hmac_sha256(secret, body).hexdigest().
  3. Hasonlítsa össze konstans időben az X-ThunderPhone-Signature értékével. (A naiv karakterlánc-összehasonlítás időzítési információkat szivárogtat.)
Pontosan azokat a bájtokat írjuk alá, amelyeket továbbítunk, ezért a nyers törzs ellenőrzése mindig működik. Ezek a bájtok a hasznos teher kanonikus JSON-szerializációját is jelentik — a kulcsok ábécésorrendben, tömör elválasztókkal (szóköz nélkül , és :), UTF-8 kódolással. Ez egy második, teljesen egyenértékű megoldást ad arra az esetre, ha a keretrendszere csak elemzett JSON-t tesz elérhetővé: szerializálja újra kanonikusan, és azon számítson HMAC-et.
Részesítse előnyben a nyers törzset — ez eggyel kevesebb lépés, és nem érintik egyes nyelvek JSON-számok oda-vissza szerializálásával kapcsolatos sajátosságai.

Melyik titkos kulcs?

Tárolja a titkos kulcsot titkoskulcs-kezelőben vagy környezeti változóban — soha ne commitolja.

Referenciamegvalósítások

Mind a négy a nyers kérési törzset ellenőrzi:

Keretrendszerspecifikus bekötés

Eszközhívások ellenőrzése

Amikor az ügynök közvetlenül meghívja valamelyik függvényeszközét (az eszköz rendelkezik endpoint mezővel), a kérés két ThunderPhone-fejlécet tartalmaz az Ön által konfigurált endpoint.headers mellett:
  • X-ThunderPhone-Call-ID — az élő hívás numerikus azonosítója.
  • X-ThunderPhone-Signature — HMAC-SHA256, amely az Ön szervezeti szintű webhooktitkával van kulcsolva, és a kérés törzsének pontos bájtjaira van számítva.
Ugyanaz a verify() segédfüggvény változtatás nélkül működik, két sajátossággal:
  1. A GET / DELETE eszközöknek nincs törzsük. Az argumentumok lekérdezési paraméterekként érkeznek, az aláírás pedig az üres bájtsorozatra van kiszámítva — tehát verify(b"", sig, secret) (Python) vagy verify(Buffer.alloc(0), sig, secret) (Node). Ne hashelje a lekérdezési karakterláncot.
  2. Az örökölt webhookot nem konfiguráló szervezeteknek nincs szervezeti titkuk. Ebben az esetben az eszközhívások csak X-ThunderPhone-Call-ID fejlécet tartalmaznak, aláírási fejlécet nem. Konfigurálja az örökölt webhookot (PUT /v1/webhook) aláírási titok beszerzéséhez, vagy hitelesítse az eszközhívásokat saját fejléccel az endpoint.headers használatával.
A webhook-módú eszközirányítás (az endpoint nélküli eszközök, amelyek telephony.tool / web.tool formában érkeznek az Ön szervezeti webhookjára) egy szokványos aláírt webhook — a fenti standard eljárás alkalmazható. Mindkét kérésformátumról lásd: Függvényeszközök.

Gyakori buktatók

A törzs feldolgozása, majd a JSON-könyvtár alapértelmezett beállításaival történő újrakiírása (szóközök a , / : után, beillesztési sorrendben rendezett kulcsok) eltérő bájtokat eredményez, és érvényteleníti a HMAC-et. Ellenőrizze a nyers törzset — vagy ha újra kell szerializálnia, pontosan egyezzen a kanonikus formánkkal: rendezett kulcsok, tömör elválasztók, UTF-8.
Az Express express.json() middleware-e felhasználja a törzsfolyamot, így elveszíti a nyers bájtokat. Kifejezetten a webhook útvonalán használja az express.raw() függvényt, vagy pufferelje a nyers törzset egy előzetes middleware-ben. Ugyanez vonatkozik a NestJS-re / Koára is — tekintse meg a „raw body” dokumentációjukat.
A JS-ben használt expected === signature, illetve a Pythonban használt expected == signature időzítésfüggő összehasonlítás. Használja rendre a crypto.timingSafeEqual vagy a hmac.compare_digest függvényt. A teljesítménybeli különbség elhanyagolható.
A közvetlen eszközvégpont-hívások aláírásához a szervezeti szintű webhooktitkot használjuk (GET /v1/webhook) — nem pedig a /v1/developer/webhook-endpoints egyes végpontjaihoz tartozó titkok valamelyikét. Használja újra ugyanazt a verify() függvényt, de ügyeljen arra, hogy az eszközútvonalakon a szervezeti titkot adja át neki.
A törzs nélküli eszközmetódusok esetében az aláírás az üres bájtsorozatra vonatkozik, így egyetlen univerzális módszer használható: a nyers kérési törzs HMAC-e, bármi is legyen az. Az URL vagy a lekérdezési karakterlánc hashelése soha nem fog egyezni.
Ha sikertelen ellenőrzés esetén 200-as választ ad vissza, a kezelő visszajátszásos támadások célpontjává válik. Sikertelen ellenőrzés esetén mindig nem 2xx választ adjon.

Következő lépések

Webhookok áttekintése

Kézbesítési szemantika, újrapróbálkozások, forrás IP-címek.

Webhookvégpontok

Több URL kezelése, titkok rotálása.

Funkcióeszközök

A két eszközmeghívási útvonal és a hozzájuk tartozó kérésformátumok.

Eszközintegrációk

Készítsen teljes, eszközökre épülő integrációt elejétől a végéig.