Een webhook is een omgekeerde API: in plaats van dat jij iets ophaalt, stuurt een externe dienst data naar jouw endpoint zodra er iets gebeurt. Handig en realtime, maar ook gevaarlijk, want dat endpoint staat open op het internet. Zonder de juiste controles kan iedereen er valse data naartoe sturen. In dit artikel beveilig je je webhooks stap voor stap.
Waarom webhooks een risico zijn
Een webhook-endpoint is publiek bereikbaar. Dat brengt concrete dreigingen mee.
- Een aanvaller stuurt valse events om je systeem te misleiden.
- Een onderschept echt bericht wordt opnieuw verzonden (replay).
- Een aanvaller overspoelt je endpoint met requests (denial of service).
- Gevoelige data in de payload lekt over een onbeveiligde verbinding.
Vertrouw niets totdat het bewezen is
Behandel elk binnenkomend webhook-request als niet-vertrouwd totdat je het tegendeel hebt bewezen. De aanname dat alleen de echte bron je URL kent, is geen beveiliging: URL's lekken via logs, proxies en fouten.
De afzender verifieren
Dit is de belangrijkste verdediging: bewijs dat het request echt van de verwachte bron komt. Welke methode je kiest, hangt af van de bron.
- Komt de webhook van Google Chat? Valideer het meegestuurde bearer-token uit de
Authorization-header. Google Chat stuurt een JWT die afhankelijk van je instelling ofwel een Google-getekend OIDC-token is (audience = je HTTP-endpoint-URL), ofwel een self-signed token vanchat@system.gserviceaccount.com(audience = je Cloud-projectnummer). Haal de publieke sleutels op, verifieer de handtekening en controleer dat de audience-claim klopt met jouw instelling. - Komt de webhook van een eigen of derde dienst? Gebruik een HMAC-handtekening: de bron tekent de payload met een gedeeld geheim en jij herberekent en vergelijkt die.
import hmac, hashlib
def geldig(payload_bytes, ontvangen_handtekening, geheim):
verwacht = hmac.new(geheim.encode(), payload_bytes, hashlib.sha256).hexdigest()
return hmac.compare_digest(verwacht, ontvangen_handtekening)
Vergelijk handtekeningen in constante tijd
Gebruik altijd een constant-time vergelijking zoals hmac.compare_digest voor handtekeningen. Een gewone string-vergelijking lekt via timing-verschillen informatie waarmee een aanvaller de handtekening stukje bij beetje kan raden. Dit is een subtiele maar reele kwetsbaarheid.
Replay-aanvallen voorkomen
Zelfs een geldig getekend bericht kan worden onderschept en opnieuw verstuurd. Bescherm je daartegen.
Replay-bescherming inbouwen
- Verwacht een timestamp in elk webhook-request.
- Weiger requests waarvan de timestamp te oud is, bijvoorbeeld ouder dan vijf minuten.
- Houd recent verwerkte message-ID's of nonces bij in een korte-termijn-cache.
- Weiger een bericht waarvan je de ID al gezien hebt.
- Combineer dit altijd met handtekeningverificatie voor volledige bescherming.
Payload valideren en afschermen
Vertrouw de inhoud niet zomaar. Valideer het schema en de waarden voordat je ermee werkt, en draai je endpoint uitsluitend over HTTPS.
Bevestig eerst, verwerk daarna
Reageer snel met een 200-status zodra je het bericht veilig hebt ontvangen en gevalideerd, en doe het echte werk asynchroon in de achtergrond. Veel bronnen sturen opnieuw als je te traag antwoordt, wat tot dubbele verwerking leidt. Bevestigen-en-dan-verwerken voorkomt dat.
Veelgestelde vragen
Is HTTPS alleen genoeg om mijn webhook te beveiligen?
Nee. HTTPS beschermt de verbinding tegen afluisteren, maar bewijst niet wie de afzender is. Je hebt ook verificatie van de afzender nodig via een token of HMAC-handtekening.
Hoe valideer ik het token van een Google Chat-app?
Haal Google's publieke sleutels op (de JWKS voor chat@system.gserviceaccount.com of de standaard Google-certificaten bij OIDC), verifieer de JWT-handtekening, en controleer dat de audience-claim overeenkomt met je projectnummer of je endpoint-URL, afhankelijk van je Authentication Audience-instelling.
Wat doe ik bij een ongeldig request?
Antwoord met een 401 of 403 en log het voorval. Verwerk de inhoud niet en geef in het antwoord geen details prijs over waarom het faalde, zodat je een aanvaller niet helpt.
Hoe roteer ik een webhook-geheim zonder downtime?
Accepteer tijdelijk zowel het oude als het nieuwe geheim, rol het nieuwe uit bij de bron, en verwijder daarna het oude. Zo blijft er geen moment waarop legitieme requests worden afgewezen.
Heb ik replay-bescherming nog nodig als ik al een handtekening controleer?
Ja. Een handtekening bewijst alleen dat het bericht authentiek en onveranderd is, niet dat het nieuw is. Een aanvaller kan een echt, geldig getekend bericht opvangen en opnieuw versturen. Een timestamp en een nonce-controle dekken dat af.
Hoe ga ik om met een stortvloed aan requests?
Zet rate-limiting op het endpoint, verwerp ongeldige requests zo vroeg mogelijk (voor zware verwerking), en doe het echte werk asynchroon. Zo blijft een denial-of-service-poging beheersbaar.
Met afzenderverificatie, replay-bescherming en strikte validatie maak je van een kwetsbaar webhook-endpoint een veilige toegangspoort tot je integratie.