Webhook beveiligen: API-sleutel of HMAC
Joey van Griethuijsen, HumanAgent
Uit de sessie: Specialist: Security
Joey van Griethuijsen van HumanAgent bespreekt in de Specialists-sessie over security hoe je een webhook in n8n beveiligt. Hij zet de API-sleutel naast HMAC-signing en laat in n8n zien hoe je met de Crypto-node een handtekening maakt. Technisch, maar het principe is in twee minuten te volgen.
Voor wie: Je bouwt of beheert koppelingen in n8n en wilt weten hoe je voorkomt dat iemand nep-berichten naar je workflows stuurt.
Waarom dit ertoe doet
Bijna elke koppeling van je webshop werkt met webhooks: een nieuwe order, een betaling, een retour of een formulier stuurt een bericht naar een URL. Wie die URL kent, kan er ook nep-berichten naartoe sturen. Denk aan een valse betaalbevestiging of een order die nooit is geplaatst. Shopify lost dit op door elke webhook te ondertekenen met HMAC-SHA256 in de header X-Shopify-Hmac-SHA256, met het client secret van je app als sleutel. Als je zelf workflows in n8n bouwt die orders, voorraad of klantdata aanraken, moet je dezelfde controle inbouwen. Een webhook zonder controle is een voordeur zonder slot, en n8n zet die controle niet standaard voor je aan.
Belangrijkste inzichten
- Joey verdeelt n8n-beveiliging in 3 lagen: server, webhook en workflow; deze clip gaat over de webhook.
- Een API-sleutel is bij elk verzoek hetzelfde: wie hem één keer ziet, kan onbeperkt berichten sturen.
- HMAC (RFC 2104, 1997) maakt per bericht een handtekening met een geheim dat nooit wordt verstuurd.
- In n8n maak je die handtekening met de Crypto-node, actie Hmac, bijvoorbeeld type SHA3-256 en encoding BASE64.
- Shopify ondertekent zijn webhooks op dezelfde manier met HMAC-SHA256 in de header X-Shopify-Hmac-SHA256.
Waar dit in Joeys verhaal zit
Joey deelt een n8n-omgeving op in 3 lagen: de server (alleen als je n8n zelf host), de webhook als punt van binnenkomst, en de workflow zelf. Deze clip gaat over de maatregelen op de webhook, met een voorbeeld van een backoffice die berichten naar een workflow stuurt om ze naar HR, IT of finance te routeren. Een webhook is een URL die berichten van buiten accepteert, bijvoorbeeld een adres dat eindigt op /webhook/reageerbericht. Zonder controle verwerkt n8n alles wat binnenkomt.
API-sleutel: simpel, maar altijd hetzelfde
De eerste maatregel is een API-sleutel: een geheim dat alleen het verzendende systeem kent en meestuurt. Een hacker die de sleutel niet heeft, komt er niet in. Het nadeel dat Joey noemt: bij elk verzoek is de sleutel hetzelfde. Wie één verzoek onderschept, of de sleutel in een log of mail vindt, kan daarna onbeperkt berichten sturen. In n8n stel je dit in de Webhook-node in via Header auth, Basic auth of JWT. Voor interne workflows kun je daar een IP(s) Allowlist naast zetten; verzoeken van andere adressen krijgen dan een 403-fout.
HMAC: een handtekening per bericht
HMAC staat voor Hash-based Message Authentication Code en is in februari 1997 vastgelegd in RFC 2104. Beide systemen kennen hetzelfde geheim, maar dat geheim gaat nooit over het internet. De verzender berekent met het geheim en de inhoud van het bericht een hash, de handtekening, en stuurt alleen die mee. Joey noemt als inhoud bijvoorbeeld het tijdstip en het ID van het record. De ontvanger rekent met hetzelfde geheim na en vergelijkt. Klopt de handtekening, dan komt het bericht van de juiste afzender en is het onderweg niet veranderd. Omdat de inhoud per bericht verschilt, is ook de handtekening elke keer anders. Joey spreekt van een privé- en een publieke sleutel. Strikt genomen is er één gedeeld geheim en is het bericht zelf het openbare deel.
De demo in n8n
In n8n doe je dit met de Crypto-node. Die kent zes acties, waaronder Hash, Sign en Hmac. Joey kiest Hmac met type SHA3-256; n8n ondersteunt verder onder meer SHA256 en SHA512. Als waarde gebruikt hij het request-ID plus een tijdstip (2025-10-07 14:30:00), als secret 'secretsauce' en als encoding BASE64. De node geeft een hash terug die je vergelijkt met de handtekening die de afzender meestuurde. Shopify werkt met hetzelfde principe: HMAC-SHA256, base64, berekend over de ruwe body van het verzoek. Neem je zoals Joey een tijdstip mee, dan kun je ook oude berichten weigeren die iemand opnieuw probeert af te spelen.
Probeer dit deze week
- Maak een lijst van alle webhook-URL's in je n8n- of Zapier-omgeving en noteer per URL welke controle erop zit: geen, sleutel, IP-lijst of HMAC.
- Zet op elke interne workflow een IP(s) Allowlist in de Webhook-node, zodat alleen je eigen systemen hem kunnen aanroepen.
- Controleer bij je Shopify- of betaalkoppeling dat de HMAC-handtekening echt wordt nagerekend voordat een order wordt verwerkt.
Begrippen
- Webhook
- Een URL waar een ander systeem automatisch een bericht naartoe stuurt zodra er iets gebeurt, zoals een nieuwe order.
- API-sleutel
- Een geheim wachtwoord dat software meestuurt om toegang te krijgen tot een systeem.
- HMAC
- Een handtekening die je berekent uit een bericht en een gedeeld geheim, zodat de ontvanger kan controleren wie het stuurde en dat het niet is gewijzigd.
- Hash
- Een vaste reeks tekens die uit een tekst wordt berekend; dezelfde invoer geeft altijd dezelfde hash.
Transcriptie
Uitgeschreven uit de audio van dit fragment. Stopwoorden en herhalingen zijn weggelaten. Waar [onverstaanbaar] staat, is de opname niet te verstaan.
De belangrijkste maatregelen hierin zijn ofwel een API-sleutel, dat is dus natuurlijk een sleutel die alleen het eerste systeem kent en niet een hacker bijvoorbeeld, die zou het niet kennen. Wel een nadeel daaraan is, elke request die wordt gestuurd, is die API-t hetzelfde. en daarom hebben we ook HMAC Security, dat is Hash Based Message Authentication Code, en dat werkt eigenlijk met een privé sleutel en een publieke sleutel. En de privé sleutel is dus alleen bekend op systeem A en op systeem B, maar die wordt nooit verstuurd. En dus is het eigenlijk een soort formule die wordt toegepast, eigenlijk een handtekening die wordt gegenereerd, op basis van iets wat dus publiek beschikbaar is, zoals het tijdstip of het ID van het record of de request die je verstuurt, in combinatie eigenlijk met die privé sleutel. Daar komt een handtekening uit, en alleen systeem A en systeem B kunnen die handtekening genereren, omdat zij de kennis hebben over die privé sleutel. En op zo'n manier, jij kunt het misschien heel even snel laten zien, dat kan je in n8n met de Crypto-node, die moet je dan hebben. En dan kun je die dus instellen op HMAC. Je kunt een type encryptie kiezen, bijvoorbeeld SHA3-256. En dan hebben we hier dus de secret. En dat is dus die privé-sleutel die eigenlijk nooit over het internet verstuurd wordt. En als we die dan runnen, dan komt er dus een hash uit eigenlijk. Dat is een soort handtekening waar ik het net over had. En deze kunnen we dan gebruiken om die te vergelijken met wat systeem A verstuurde naar systeem B.
Spreker: Joey van Griethuijsen, HumanAgent
Bronnen
Meer over Security & Beleid
Duur 1:20Wat NOOIT te delen met AI
Jop van Hooft, eCommerce AI Club
API-keys worden net zo makkelijk gedeeld als lunchplannen, en dat is gevaarlijk
Duur 1:37Te ruime toegangsrechten bij AI-agents
Joey van Griethuijsen, HumanAgent
n8n's eigen website gaf een AI-agent onnodig toegang tot Entra en Jira
Duur 1:42Data classificatie: hash, postcode en deep links
Jop van Hooft, eCommerce AI Club
Hash je e-mails, bewaar 4 cijfers postcode, deep-link naar Magento