X-ThunderPhone-Signature. Implementeer de verificatie één keer correct
en gebruik dezelfde helper in elke handler.
Het algoritme
- Lees de onbewerkte requestbody — de exacte bytes die we naar je POSTen.
- Bereken
hmac_sha256(secret, body).hexdigest(). - Vergelijk in constante tijd met
X-ThunderPhone-Signature. (Een naïeve tekenreeksvergelijking lekt timinginformatie.)
, en : zonder spaties), UTF-8. Dit biedt je een tweede, volledig
gelijkwaardige aanpak wanneer je framework alleen geparseerde JSON beschikbaar
maakt: serialiseer canoniek opnieuw en bereken daarover de HMAC.
Welk secret?
Sla het secret op in je secretmanager of omgevingsvariabele — commit het nooit.
Referentie-implementaties
Alle vier verifiëren de onbewerkte requestbody:Frameworkspecifieke integratie
Toolaanroepen verifiëren
Wanneer de spraakagent rechtstreeks een van je functietools aanroept (de tool heeft eenendpoint), bevat het verzoek naast je geconfigureerde
endpoint.headers twee ThunderPhone-headers:
X-ThunderPhone-Call-ID— de numerieke id van het actieve gesprek.X-ThunderPhone-Signature— HMAC-SHA256, met je webhookgeheim op organisatieniveau als sleutel, over de exacte bytes van de aanvraagbody.
verify()-helper werkt ongewijzigd, met twee nuances:
GET- /DELETE-tools hebben geen body. Argumenten worden als queryparameters doorgegeven en de handtekening wordt berekend over de lege bytestring — dusverify(b"", sig, secret)(Python) ofverify(Buffer.alloc(0), sig, secret)(Node). Hash de querystring niet.- Organisaties zonder geconfigureerde verouderde webhook hebben geen
organisatiegeheim. In dat geval bevatten toolaanroepen alleen
X-ThunderPhone-Call-IDen geen handtekeningheader. Configureer de verouderde webhook (PUT /v1/webhook) om een ondertekeningsgeheim te krijgen, of verifieer toolaanroepen met je eigen header viaendpoint.headers.
endpoint, geleverd
aan je organisatiewebhook als telephony.tool / web.tool) is een
gewone ondertekende webhook — het standaardrecept hierboven is van
toepassing. Zie Functietools voor beide
aanvraagvormen.
Veelvoorkomende valkuilen
Opnieuw serialiseren met standaardopmaak
Opnieuw serialiseren met standaardopmaak
De body parsen en opnieuw dumpen met de standaardinstellingen van je
JSON-bibliotheek (spaties na
, / :, sleutels in invoegvolgorde) produceert
andere bytes en breekt de HMAC. Verifieer de onbewerkte body — of als
je opnieuw moet serialiseren, volg dan exact onze canonieke vorm: gesorteerde
sleutels, compacte scheidingstekens, UTF-8.Framework parseert JSON automatisch
Framework parseert JSON automatisch
De
express.json()-middleware van Express verbruikt de bodystream
en je verliest de onbewerkte bytes. Gebruik specifiek express.raw() op de
webhookroute, of buffer de onbewerkte body in een pre-middleware.
Hetzelfde geldt voor NestJS / Koa — bekijk hun documentatie over de “raw body”.Niet timing-safe vergelijken
Niet timing-safe vergelijken
expected === signature in JS of expected == signature in
Python zijn vergelijkingen met variabele timing. Gebruik respectievelijk crypto.timingSafeEqual
of hmac.compare_digest. Het prestatieverschil
is nihil.Verkeerd secret voor tool-endpoints
Verkeerd secret voor tool-endpoints
Rechtstreekse aanroepen van tool-endpoints worden ondertekend met het webhooksecret
op organisatieniveau (
GET /v1/webhook) — niet met een secret per eindpunt
uit /v1/developer/webhook-endpoints. Hergebruik dezelfde verify()
functie, maar zorg dat je deze op toolroutes het organisatiesecret geeft.De querystring hashen bij GET/DELETE-tools
De querystring hashen bij GET/DELETE-tools
Voor toolmethoden zonder body omvat de handtekening de lege bytestring,
waardoor je één universele werkwijze behoudt: HMAC de onbewerkte requestbody,
wat die ook is. De URL of querystring hashen komt nooit overeen.
Geen 401 retourneren bij mismatch
Geen 401 retourneren bij mismatch
Een 200 retourneren bij mislukte verificatie maakt de handler een doelwit
voor replayaanvallen. Geef altijd een niet-2xx-status terug als verificatie mislukt.
Volgende stappen
Webhookoverzicht
Leveringssemantiek, retries, bron-IP’s.
Webhook-eindpunten
Beheer meerdere URL’s, roteer secrets.
Functietools
De twee paden voor toolaanroepen en hun requeststructuren.
Toolintegraties
Bouw een complete integratie met tools van begin tot eind.