Een webhook-handtekening is een gecodeerd stempel bij een webhook-bericht dat twee dingen bewijst: dat het bericht echt van de afzender komt die het beweert, en dat niemand het onderweg heeft veranderd. Omdat een webhook gewoon een HTTP-verzoek is naar een URL die iedereen kan ontdekken, is de handtekening wat een echte melding van een vervalste scheidt.
Het idee in gewone woorden. De afzender en jouw server delen vooraf een geheime sleutel. Wanneer de afzender een webhook afvuurt, haalt hij het bericht en het geheim door een eenrichtings-hashing-functie tot een handtekening, en stuurt beide mee. Jouw server doet exact dezelfde berekening met zijn eigen kopie van het geheim. Komen de handtekeningen overeen, dan is het bericht betrouwbaar. Zo niet, dan gooi je het weg.
Het werkt als een lakzegel op een brief. Alleen iemand met het juiste stempel kan het zetten, en een gebroken zegel vertelt je dat de inhoud is aangeraakt. Dat gedeelde geheim veilig houden is de hele kunst, en daarom hoort het in goed secrets management thuis in plaats van zichtbaar in de code.
Twee praktische details laten mensen struikelen. Ten eerste moet je de ruwe inhoud van het verzoek hashen precies zoals die binnenkwam, byte voor byte, want eerst de JSON herformatteren verandert de uitkomst en dan klopt elke controle niet meer. Ten tweede stoppen veel providers een tijdstempel in de ondertekende data, zodat een aanvaller een echt bericht niet uren later opnieuw kan afspelen, dus weiger alles wat te oud is.
Bij TopDevs controleren we de handtekening van elke binnenkomende webhook in de koppelingen die we bouwen, zodat de automatiseringen van een klant alleen reageren op berichten waarvan we kunnen bewijzen dat ze echt zijn.
