Een webhook laat een systeem automatisch een ander systeem informeren zodra er iets gebeurt, zoals een nieuwe bestelling of een gewijzigde voorraad. Lees hoe dat technisch werkt, wanneer een webhook handiger is dan periodiek gegevens ophalen en hoe je omgaat met beveiliging, storingen en dubbele meldingen.
Wat is een webhook en hoe werkt een melding?
Een webhook is gewoon een manier waarop systemen elkaar een bericht sturen als er iets gebeurt. Stel je verkoopt iets via een webshop. Zodra de klant betaalt, kan de webshop automatisch de boekhouding informeren. Dat gebeurt door een HTTP-verzoek te sturen naar een ingestelde URL die hoort bij het ontvangende systeem. In de praktijk is dat meestal een POST-verzoek met een beetje informatie over de gebeurtenis: bijvoorbeeld het bestelnummer, de nieuwe status of het tijdstip.
Bij een webhook spelen drie stukken een rol: de gebeurtenis die plaatsvindt, het adres waar de melding heen gaat (de bestemming), en het systeem dat deze oppakt (de ontvanger). Een gebeurtenis kan echt van alles zijn: een nieuwe klant, een order die de deur uitgaat, voorraad die wijzigt. Als het zover is, stuurt het bronsysteem een melding naar het webhook-endpoint. De ontvanger checkt het verzoek en stuurt een HTTP-status terug. Een code uit de 2xx-reeks geeft (meestal) aan dat het goed is aangekomen, een foutcode kan een retry triggeren.
Zo’n webhook bevat niet standaard alle informatie. Je krijgt meestal een beperkte set, zoals het ID plus wat context, niet een complete gegevensset. Wil je meer, dan vraag je die op via een API met het ID. Kleine berichten, snelle reactie. Let er wel op: het feit dat je een webhook ontvangt betekent niet dat alles automatisch synchroon loopt. Het geeft alleen aan dat er iets is veranderd.
Webhook tegenover polling: push of periodiek ophalen
Bij polling komt het initiatief van de ontvanger: die vraagt telkens (om de paar minuten, per uur, één keer per dag, het kan allemaal) bij het andere systeem of er wat gebeurd is. Een webhook werkt anders: het bronsysteem laat direct weten dat er nieuws is. En dat is niet alleen technisch een verschil. Het beïnvloedt ook hoe snel je wijzigingen ziet, hoe vaak systemen praten, en hoe je omgaat met fouten.
Polling snapt bijna iedereen meteen. Best handig als je geen haast hebt. Stel: je wilt alleen elke middag even checken of je prijzen kloppen. Nadeel is dat het vaak loze verzoeken oplevert. Je kunt korter op de bal spelen door vaker te vragen, maar dan groeit het aantal API-calls snel. Als je juist minder wilt belasten, kies je een langere interval, alleen duurt verandering dan wat langer voordat die doorkomt.
Webhooks geven sneller een seintje en besparen onnodig verkeer. Maar dan moet de ontvanger wel bereikbaar zijn en elk bericht goed verwerken, ook als er ineens veel tegelijk komen of iets vertraging oploopt. In de echte wereld staan systemen zelden helemaal los van elkaar: je ziet regelingen waarbij de webhook nieuws brengt, en een geplande taak af en toe alsnog checkt of je niks gemist hebt. Daarmee voorkom je verrassingen door bijvoorbeeld een tijdelijk netwerkprobleem. Welke aanpak bij jou past, hangt af van hoeveel actualiteit je nodig hebt, waar je API’s ruimte laten, en wat het kost om iets te missen.
Van gebeurtenis tot verwerking: de route van een webhook
Eerst moet je aangeven welke gebeurtenissen je wilt doorgeven en waar ze heen moeten. Dat doe je meestal in een beheeromgeving van het bronsysteem. Daarna wachten beide systemen. Komt er bijvoorbeeld een afgeronde betaling binnen? Dan maakt het bronsysteem een HTTP-verzoek met de gebeurtenisnaam en bijhorende data, richting de URL die jij opgeeft. Het verzoek reist via HTTPS naar jouw server, die het bericht ontvangt, controleert (bijvoorbeeld met een handtekening) en bepaalt wat ermee gebeurt.
Een handig endpoint houdt de verwerking eerst zo klein mogelijk. Checkt alleen even of het bericht klopt, zet hem (desnoods) door naar een wachtrij en stuurt dan direct een HTTP 200 terug. Daarna mag een achtergrondproces het bericht rustig verder afhandelen. Scheelt tijd en voorkomt dat de oorspronkelijke afzender denkt dat er iets mis is omdat bijvoorbeeld je boekhoudsoftware even traag reageert.
Een fout die veel voorkomt: alles in het webhookproces proppen. Dus het externe systeem wachten laten op een trage koppeling, waardoor die een time-out krijgt, en hetzelfde bericht nog eens stuurt. Met een wachtrij koppel je ontvangst los van verwerking. Je moet die buffer echter ook beheren: een bericht kan aan blijven haken, vastlopen of helemaal niet te verwerken zijn. Maak dus zichtbaar wat er met een melding gebeurt nadat die binnenkomt, niet alleen of je endpoint een HTTP-code teruggaf.
Een bruikbaar webhook-event ontwerpen
Je haalt meer uit een integratie door meteen bruikbare informatie in het event mee te sturen. Geef ieder event een duidelijke naam, een unieke ID, en alles wat nodig is om het te herleiden. Namen als order.created zijn in één oogopslag duidelijk, termen als update totaal niet. Een tijdstip en een objectreferentie horen erbij, net als een versienummer van het eventformaat als je die gebruikt.
Volledige data meesturen heeft z’n voordelen: dan kan de ontvanger gelijk aan de slag. Maar dat maakt het bericht groter en mogelijk vatbaar voor verouderde informatie. Met alleen een ID is het event beknopt, maar moet de ontvanger soms een extra call doen. In de praktijk voegt men vaak de belangrijkste kerngegevens mee, plus een ID voor detailophaal. Kies voor wat dagelijks nodig is, en hou gevoelige data buiten de webhook tenzij echt nodig.
Laat een structurele wijziging in het eventformaat nooit ongemerkt binnensluipen. Schrap je velden of verander je betekenis, dan breek je bestaande integraties zonder waarschuwing. Voeg nieuwe velden toe als optioneel en documenteer goed wat verplicht is. Grote wijzigingen? Nieuwe versie doen, en oude events voorlopig laten bestaan. Check ook goed hoe je omgaat met lege waarden, tijdzones, valuta en statussen: verwarring daarover zorgt razendsnel voor foutjes. Denk aan je eventcontract als meer dan een JSON-schema: het is een bindende afspraak voor verwerking en controle.
Webhooks beveiligen met HTTPS, handtekeningen en geheimen
Een webhook-endpoint is een open deur naar je applicatie. Zet daarom altijd HTTPS aan, zodat alles versleuteld loopt. Alleen daarmee ben je er niet. Controleer óók of het verzoek echt komt van wie je verwacht. Handtekeningen zijn daarbij praktisch: de verzender berekent met een geheim een HMAC van de body en plakt dat als header erbij. Jij berekent hetzelfde op jouw manier en vergelijkt de uitkomst. Laat het daar niet bij. Doe die vergelijking zo dat je geen lekken toelaat op subtiele verschillen (timing attacks, bijvoorbeeld).
Sta niet alleen toe op basis van URL of IP-adres. Een URL kan worden doorgegeven, IP’s kunnen wisselen, sommige platforms draaien voor meer klanten tegelijk. Als je een IP-allowlist gebruikt, zet die in als extra laag, niet als enige filter. Sla geheime sleutels veilig op, geef toegang alleen aan wie ze nodig heeft en regel meteen hoe je geheimen tijdig vervangt. Houd er rekening mee dat je bij vervanging even oud en nieuw geheim tegelijk moet accepteren, anders loop je kans berichten te missen.
Beperk verder wat je endpoint mag met ontvangen data. Valideer eerst veldnamen en hun inhoud, voorkom dat je systemen als proxy voor andermans verzoeken gebruikt, en laat foutcodes zó zien dat je niet per ongeluk interne details weggeeft. Hoe meer persoonsgegevens in het event zitten, hoe spaarzamer je moet loggen. En als je een tijdstip in de signering verwerkt, voorkom je dat een afgevangen bericht later een tweede leven krijgt. Beveiliging vraagt om samenhangende maatregelen; een geldige handtekening betekent niet automatisch veilige afhandeling.
Wat gebeurt er als een webhook niet aankomt?
Het komt regelmatig voor dat een webhook-melding niet aankomt. Misschien is het endpoint even onbereikbaar, misschien valt het netwerk uit, of loopt er een time-out. De applicatie kan ook simpelweg weigeren wegens een fout. Veel aanbieders sturen zulke verzoeken automatisch opnieuw, maar hoe dat gebeurt verschilt. Soms is er een maximum aantal pogingen, soms loopt de vertraging steeds verder op. Je zult dus zelf moeten nakijken welke HTTP-codes als ‘geslaagd’ gelden, hoe lang retries duren en of je gemiste meldingen handmatig kunt triggeren.
De ontvangende kant moet vooral rap en eenduidig reageren. Een 2xx-code betekent eigenlijk alleen: ik heb het bericht ontvangen, niet dat alles in de backend al klaar is. Sla het event daarom liever eerst duurzaam op voordat je succes meldt. Gaat daar iets mis, stuur dan een fout terug. Anders denkt de verzender dat het bericht afgeleverd is, terwijl het in werkelijkheid ergens tussen wal en schip is geraakt.
Nog een punt: retries lossen niet alles op. Tijdelijke storingen gaan vanzelf voorbij, maar als het event een fout bevat (onbekend veld, verkeerde structuur), dan struikelt elke poging opnieuw. Maak onderscheid tussen tijdelijk en definitief mislukte berichten. Zet onoplosbare fouten in een dead-letter queue of maak ze zichtbaar, zodat je ze handmatig kunt onderzoeken en opnieuw afhandelen. Anders raak je gebeurtenissen kwijt waar pas later iets geks door opvalt.
Dubbele meldingen en volgorde betrouwbaar verwerken
Meldingen komen soms vaker binnen dan je verwacht. Niet raar: als een verzender geen bevestiging ziet, weet die niet of het verzoek überhaupt aankwam of alleen het antwoord zoek raakte. Extra aanbod is dus normaal. Verwerking moet tegen dubbelen kunnen: een order mag niet dubbel geboekt worden, een betaling ook niet.
Hier helpt het om elke event-ID op te slaan. Zo krijg je idempotente verwerking. Herhaling levert dan steeds hetzelfde eindresultaat op. Schrijf die check en mutatie waar mogelijk samen in één transactie. Gebeurt dat niet, en faalt er iets tussenin, dan kan een retry alsnog twee keer dezelfde mutatie uitvoeren.
Let verder op de volgorde. Een event over een latere status (bijvoorbeeld shipment.completed) kan eerder binnenkomen dan een oudere status, door retries of verschillende paden. Ga dus niet uit van binnenkomstvolgorde. Bekijk datum, versienummer of status zelf om te bepalen of iets actueler is. Alleen een tijdstip is soms onvoldoende: klokken kunnen van elkaar verschillen, of meerdere events krijgen elk hetzelfde tijdstip. In geval van twijfel mag je de actuele situatie ophalen bij de bron. Dat vraagt wat meer van de API, maar voorkomt dat een late melding oude informatie terugzet.
Webhooks testen, monitoren en storingen opsporen
Vertrouwen op ‘geen nieuws is goed nieuws’ werkt hier niet. Je wilt weten wat er gebeurt als een event binnenkomt. Begin met loggen: noteer event-ID, binnenkomsttijd, of de handtekening geldig was, de verwerkingsstatus en de foutsoort als het misgaat. Probeer alleen volledige payloads weg te laten in je logs als daar persoonsgegevens of geheime info in zitten. Gebruik een correlatie-ID zodat je een event in alle systemen makkelijk terugvindt.
Kijk niet alleen of de endpoint-URL bereikbaar is. Let daarbij op groeipercentages: hoeveel verzoeken mislukken, hoelang is het oudste bericht in de wachtrij, hoeveel retries lopen er nog? Het kan zomaar zijn dat je endpoint netjes een 200 teruggeeft, maar de achtergrondverwerking is gestopt. Bedenk dat je meldingen wilt krijgen bij afwijkingen die iemand aandacht vragen, niet bij elk zeldzaam of tijdelijk foutje. Anders loop je het risico urgente meldingen te missen temidden van de massa.
Test alle scenario’s, niet alleen min of meer perfecte cases. Dus: probeer expres foutieve handtekeningen, dubbele berichten, incomplete payloads, vertraagde achterliggende processen, kapotte endpoints. Kijk wat er gebeurt als je systeem herstart of als een fout net te laat hersteld is. Zorg altijd dat je testomgeving losstaat van de productie, en voorkom dat testtransacties stiekem echte data schrijven. Sla bovendien een manier op om events later opnieuw af te spelen: dat kan uitkomst bieden na een storing, maar brengt risico’s als de situatie inmiddels veranderd is.
Webhooks inzetten tussen webshop, ERP en voorraadbeheer
Koppel je een webshop en een ERP, dan kun je webhooks voor heel wat berichten inzetten: order aangemaakt, bestelling in de verzending, voorraad gewijzigd. De webshop meldt een order, het ERP stuurt terug dat een zending onderweg is. Een platform dat voorraad beheert kan mutaties rechtstreeks pushen naar elk verkoopkanaal. Door alleen te versturen wat nodig is aan het juiste systeem, bespaar je tijd en verkeer en zijn gegevens sneller bijgewerkt.
Maar let op: webhooks lossen niet álles op. Per gegeven moet je bepalen welk systeem leidend is. Staat voorraad zowel in de webshop als in het ERP open voor handmatige aanpassing, dan kun je in een eindeloze lus belanden. Spreek dus per categorie af welke bron bepaalt, bijvoorbeeld voor prijs, klant of voorraad. En sla de oorsprong van een wijziging op, zodat je kunt voorkomen dat een update dezelfde informatie eindeloos heen en weer stuurt.
Verder: wat betekent een melding nou echt in het proces? Een bericht dat een order is aangemaakt zegt niks over de betaling en evenmin over gereserveerde voorraad. Behandel deelacties (statusupdate, levering, betaling) als losse gebeurtenissen, of check vooraf wat de actuele status is. Op het ene moment is een vertraging in voorraad niet erg, bij een grote kortingsactie kan het leiden tot verkoop overschrijding. Dan zijn reserveringen en achteraf vergelijken onmisbaar. Dus sluit je webhookgebruik aan bij de praktijk: fouten in het proces zijn niet altijd technisch direct zichtbaar.
Wanneer webhooks niet volstaan en een controle nodig blijft
Als je helemaal wilt vertrouwen op webhooks, mis je soms iets. Bij uitval van de verzender, verkeerde configuratie of een bericht in een foutwachtrij, blijft een update hangen. Dus voor zaken waar ontbrekende data echt telt, betalingen, voorraad, rapportages, blijft periodiek vergelijken de enige zekere weg.
Reconciliatie werkt vaak zo: pak alle orders die jouw webshop als betaald kent en vergelijk die met de betalingen uit het boekhoudpakket. Je hoeft niet steeds alles op te halen: recente wijzigingen vergelijken is meestal genoeg, af en toe scan je breder. Let op paginering, limieten en tijdzones in de API. Vertrouw je alleen maar op tijdstempels, dan mis je events als iets precies op het snijpunt valt, of data pas later zichtbaar wordt.
Er zijn ook leveranciers zonder webhook, of hun events zijn niet precies genoeg, of je hebt data uit verschillende bronnen nodig. Soms is een mix handig: webhook voor snelle signalen, periodieke polling of reconciliatie als vangnet. Maar dat maakt de puzzel ook ingewikkelder. Je zult vast moeten leggen wie beslist bij een verschil, en hoe fouten opgelost worden, anders kun je bij elke poging oude data over versere heen schrijven.