technisch · antwoord met bronnen
Webhookhandtekeningen verifiëren
Het verifiëren van een webhookhandtekening is een beveiligingsproces waarbij een ontvanger een cryptografische handtekening bij een inkomend HTTP-request valideert. Zo weet je zeker dat de payload door de vertrouwde provider is verstuurd en onderweg niet is gewijzigd.
Definitie
Het verifiëren van webhookhandtekeningen is een mechanisme om de bron van een webhookevent te authenticeren. Stuurt een provider zoals Resend of SendGrid een notificatie over een e-mailevent, dan voegt hij een hash van de payload toe die met een geheime sleutel is ondertekend. De ontvangende server gebruikt dezelfde geheime sleutel om de hash opnieuw te berekenen en vergelijkt die met de handtekening in de requestheader.
Hoe het proces werkt
De provider genereert een HMAC-hash op basis van een gedeeld geheim en de body van het request. Deze hash wordt meegestuurd in een header, vaak X-Signature of iets vergelijkbaars. De ontvanger legt de ruwe requestbody en de handtekeningheader vast en berekent vervolgens zelf een HMAC-hash met het gedeelde geheim. Komt de berekende hash overeen met de headerwaarde, dan is het request authentiek. Verschillen ze, dan wordt het request als onbevoegd geweigerd.
Waarom het belangrijk is voor afzenders
Zonder verificatie kan iedereen die je webhook-URL kent nepdata naar je server sturen. Dat kan leiden tot onjuiste database-updates, zoals een afgeleverde e-mail die als gebounced wordt gemarkeerd. Met verificatie voorkom je spoofingaanvallen en zorg je dat je applicatie alleen reageert op legitieme events uit je eigen e-mailinfrastructuur.
Praktische aandachtspunten
Een veelgemaakte fout is de requestbody naar een JSON-object parsen voordat je de handtekening verifieert. Omdat JSON-parsers witruimte of de volgorde van keys kunnen wijzigen, komt de resulterende string mogelijk niet overeen met de oorspronkelijke payload van de provider. Gebruik voor HMAC-berekeningen altijd de ruwe, ongeparste requestbody om mislukte verificaties te voorkomen.
Implementatievoorbeeld
In een Node.js-omgeving gebruikt een developer de crypto-module om met het geheim van de provider een HMAC-SHA256-hash van de ruwe body te maken. Het resultaat wordt vervolgens met een constant-time vergelijkingsfunctie vergeleken met de handtekeningheader, om timingaanvallen te voorkomen. SendHQ biedt gratis tools op https://sendhq.cc/tools om de e-mailconfiguraties te beheren die vaak aan een webhooksetup voorafgaan.
Vragen die teams stellen
Wat gebeurt er als de geheime sleutel uitlekt?
Is de geheime sleutel gecompromitteerd, dan kan een aanvaller nep-requests ondertekenen die je server als geldig accepteert. Roteer de geheime sleutel dan direct in het dashboard van je provider en werk de omgevingsvariabelen op je server bij.
Maakt HTTPS het verifiëren van handtekeningen overbodig?
Nee. HTTPS versleutelt de data onderweg en verifieert de identiteit van de server, maar controleert niet of de client die het request stuurt je geautoriseerde e-mailprovider is.
Waarom HMAC gebruiken in plaats van een eenvoudige API-sleutel?
HMAC-handtekeningen bewijzen dat er niet met de inhoud van het bericht is geknoeid. Een statische API-sleutel in een header bewijst alleen dat de afzender de sleutel kent, niet dat de payload intact is.
Primaire bronnen
- Resend-documentatie — Resend
- Postmark-documentatie voor developers — Postmark
- SendGrid-documentatie — Twilio SendGrid