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 een automatische melding van het ene systeem aan het andere wanneer een bepaalde gebeurtenis plaatsvindt. Denk aan een webshop die een boekhoudpakket informeert zodra een betaling is geslaagd. Het systeem waarin de gebeurtenis ontstaat, verstuurt dan een HTTP-verzoek naar een vooraf ingestelde URL van het ontvangende systeem. Meestal is dat een POST-verzoek met gegevens over de gebeurtenis, bijvoorbeeld een bestelnummer, status en tijdstip.
De werking bestaat uit drie onderdelen: een gebeurtenis, een bestemming en een ontvanger. De gebeurtenis kan bijvoorbeeld een nieuwe klant, een verzonden bestelling of een voorraadwijziging zijn. De bestemming is een endpoint: een URL die het ontvangende systeem beschikbaar stelt. De ontvanger verwerkt het verzoek en geeft een HTTP-statuscode terug. Een code uit de 2xx-reeks betekent doorgaans dat het verzoek is ontvangen; een foutcode kan aanleiding zijn om opnieuw te proberen.
Een webhook verstuurt niet vanzelf een complete synchronisatie van alle gegevens. Vaak bevat de melding alleen een identificatie en beperkte context. De ontvanger kan daarna, indien nodig, via een API de actuele details ophalen. Zo blijft de melding klein en kan het ontvangende systeem zelf bepalen welke informatie nodig is. Dat onderscheid is belangrijk: een webhook meldt dat er iets veranderde, maar is niet automatisch een garantie dat beide systemen volledig gelijk blijven.
Webhook tegenover polling: push of periodiek ophalen
Bij polling vraagt een systeem op vaste momenten aan een ander systeem of er nieuwe gegevens zijn. Dat kan iedere minuut, ieder kwartier of eenmaal per dag gebeuren. Een webhook werkt andersom: het bronsysteem stuurt een melding zodra een relevante gebeurtenis plaatsvindt. Het verschil is dus niet alleen technisch, maar ook een keuze over snelheid, belasting en foutafhandeling.
Polling is eenvoudig te begrijpen en kan nuttig zijn wanneer wijzigingen niet direct hoeven door te komen. Een dagelijkse controle van productgegevens kan bijvoorbeeld voldoende zijn. De keerzijde is dat veel verzoeken niets nieuws opleveren. Een korte interval vermindert de vertraging, maar verhoogt het aantal API-aanroepen en kan limieten van een leverancier raken. Een lange interval spaart capaciteit, maar laat informatie langer verouderd.
Webhooks kunnen wijzigingen sneller doorgeven en vermijden onnodige controles. Daar staat tegenover dat de ontvanger bereikbaar moet zijn en inkomende meldingen betrouwbaar moet verwerken. Ook moet rekening worden gehouden met herhaalde of vertraagde verzoeken. In de praktijk worden beide methoden vaak gecombineerd: webhooks voor snelle signalering en een periodieke controle om gemiste wijzigingen te herstellen. Die controle voorkomt dat een tijdelijke storing ongemerkt een blijvend verschil tussen systemen veroorzaakt. De juiste keuze hangt af van de gewenste actualiteit, beschikbare API-functies en de impact van een gemiste of vertraagde update.
Van gebeurtenis tot verwerking: de route van een webhook
Een webhook begint met een configuratie. De beheerder kiest welke gebeurtenissen meldingen opleveren en geeft de URL van het ontvangende endpoint op. Wanneer bijvoorbeeld een betaling wordt afgerond, maakt het bronsysteem een verzoek met een gebeurtenisnaam en bijbehorende gegevens. Dat verzoek reist via HTTPS naar de server van de ontvanger. Die server controleert eerst of de melding geldig is en bepaalt daarna wat ermee moet gebeuren.
Een robuust endpoint doet zo min mogelijk werk voordat het antwoord geeft. Het controleert bijvoorbeeld de handtekening, valideert de basisstructuur en plaatst het bericht in een wachtrij. Vervolgens antwoordt het snel met een succesvolle statuscode. Een aparte achtergrondtaak kan de bestelling daarna verwerken in een ERP-systeem, voorraadadministratie of boekhouding. Zo hoeft de verzender niet te wachten op een lange verwerking en verkleint de kans op een time-out.
Een veelvoorkomende fout is om alle verwerking rechtstreeks in het webverzoek uit te voeren. Als een externe API traag is, kan het endpoint te laat antwoorden. De verzender ziet dan mogelijk een fout en stuurt dezelfde melding opnieuw, terwijl de eerste verwerking nog loopt. Een wachtrij maakt die stappen losser gekoppeld en geeft ruimte om tijdelijk werk op te vangen. Wel moet de organisatie ook die wachtrij beheren: berichten kunnen vastlopen, zich opstapelen of structureel niet verwerkbaar blijken. De route van melding tot resultaat moet daarom zichtbaar zijn, niet alleen het moment waarop het endpoint een verzoek ontving.
Een bruikbaar webhook-event ontwerpen
De kwaliteit van een integratie hangt sterk af van de informatie die een gebeurtenis bevat. Een event heeft minimaal een herkenbare naam, een unieke event-ID en gegevens waarmee de ontvanger de wijziging kan verwerken. Namen als order.created of inventory.changed zijn duidelijker dan algemene termen als update. Een tijdstip en een verwijzing naar het betreffende object helpen bij controles en foutonderzoek. Vermeld ook welke versie van het eventformaat wordt gebruikt.
De afweging tussen een volledig gegevensobject en een kleine melding is belangrijk. Een volledige bestelling in de payload kan verwerking versnellen, maar vergroot de kans op verouderde of gevoelige informatie. Een melding met alleen een order-ID is compacter en beperkt gegevensdeling, maar vraagt mogelijk om een extra API-aanroep. Een praktische middenweg bevat de velden die voor veel ontvangers nodig zijn, plus een identificatie waarmee aanvullende gegevens veilig kunnen worden opgehaald.
Verander het formaat niet stilzwijgend. Als een veld verdwijnt of van betekenis verandert, kan bestaande ontvangende software fouten maken zonder dat de webhook zelf faalt. Voeg uitbreidingen bij voorkeur achterwaarts compatibel toe en documenteer verplichte en optionele velden. Wanneer een wezenlijke wijziging nodig is, maak dan een nieuwe versie of geef ontvangers een overgangsperiode. Denk ook na over lege waarden, tijdzones, valuta en statussen: een onduidelijk onderscheid tussen onbekend, leeg en nul leidt snel tot verkeerde gegevens. Een eventcontract is dus niet alleen een JSON-structuur, maar een afspraak over betekenis en gedrag.
Webhooks beveiligen met HTTPS, handtekeningen en geheimen
Een webhookendpoint is een ingang naar een applicatie en moet daarom als een beveiligingsgrens worden behandeld. Gebruik HTTPS zodat de inhoud onderweg versleuteld is. Controleer daarnaast dat een verzoek echt afkomstig is van de verwachte verzender. Een veelgebruikte methode is een digitale handtekening: de verzender berekent met een gedeeld geheim een HMAC over de ruwe request body en stuurt de uitkomst mee in een header. De ontvanger berekent dezelfde waarde en vergelijkt die op een manier die geen informatie over verschillen lekt.
Vertrouw niet alleen op een herkenbare URL of op een IP-adres. URL’s kunnen uitlekken en IP-adressen kunnen veranderen, terwijl gedeelde infrastructuur soms meerdere klanten bedient. Een IP-allowlist kan als extra laag helpen, maar vervangt geen cryptografische controle. Bewaar geheimen in een geschikte secrets-opslag, beperk wie erbij kan en plan hoe ze worden vervangen. Tijdens een rotatie kan tijdelijk acceptatie van een oud en nieuw geheim nodig zijn, zodat de koppeling niet onverwacht uitvalt.
Beperk ook wat een endpoint met de ontvangen gegevens doet. Valideer velden en lengtes, voorkom dat willekeurige URL’s uit payloads serververzoeken kunnen starten en geef geen gevoelige foutdetails terug. Controleer waar mogelijk een tijdstempel in de handtekening, zodat een eerder onderschept verzoek niet onbeperkt opnieuw kan worden aangeboden. Houd rekening met persoonsgegevens: log niet standaard volledige payloads als daar klant- of betaalinformatie in staat. Beveiliging vraagt om meerdere maatregelen, omdat een correcte handtekening op zichzelf niet voorkomt dat een geldige melding verkeerd wordt verwerkt.
Wat gebeurt er als een webhook niet aankomt?
Een melding kan onderweg mislukken doordat de ontvanger tijdelijk niet bereikbaar is, een netwerkverbinding wegvalt of het endpoint een time-out geeft. Ook kan de applicatie een foutstatus terugsturen omdat een afhankelijk systeem niet beschikbaar is. Veel webhookdiensten proberen zulke verzoeken opnieuw, maar de precieze regels verschillen. Ze kunnen bijvoorbeeld een beperkt aantal pogingen doen met steeds langere tussenpozen. Controleer daarom welke statuscodes als succesvol gelden, hoe lang opnieuw proberen doorgaat en of een beheerder een melding handmatig opnieuw kan versturen.
De ontvanger moet snel en ondubbelzinnig antwoorden. Een succesvolle statuscode betekent meestal: het verzoek is geaccepteerd, niet noodzakelijk dat alle achterliggende werkzaamheden klaar zijn. Dat is een goede reden om na validatie eerst een bericht duurzaam in een wachtrij op te slaan en dan pas succes terug te geven. Als het opslaan in die wachtrij mislukt, hoort het endpoint geen succes te melden. Anders denkt de verzender dat de melding veilig is afgeleverd, terwijl de ontvanger haar heeft laten verdwijnen.
Opnieuw proberen lost niet iedere fout op. Een tijdelijke time-out kan vanzelf verdwijnen, maar een payload met een onbekend verplicht veld faalt mogelijk bij iedere poging. Maak onderscheid tussen tijdelijke en blijvende fouten, en zorg dat problematische berichten apart zichtbaar blijven. Een dead-letter queue kan meldingen bewaren die na herhaalde pogingen niet verwerkt zijn. Leg vast hoe medewerkers die berichten onderzoeken en opnieuw aanbieden. Zonder zo’n proces kan een bericht wel technisch bewaard zijn, maar blijft een voorraadwijziging of factuur in de praktijk alsnog onafgehandeld.
Dubbele meldingen en volgorde betrouwbaar verwerken
Een webhook kan meer dan één keer aankomen. Dat gebeurt vaak bewust: als de verzender geen antwoord ontvangt, kan die niet weten of het verzoek de ontvanger niet bereikte of dat alleen het antwoord verloren ging. Daarom is opnieuw aanbieden normaal gedrag en geen uitzondering. De ontvanger moet een melding veilig kunnen verwerken zonder dat dezelfde bestelling tweemaal wordt aangemaakt of een betaling dubbel wordt geboekt.
Gebruik daarvoor een unieke event-ID en maak verwerking idempotent. Dat betekent dat een herhaalde uitvoering hetzelfde eindresultaat oplevert als één uitvoering. Bewaar bijvoorbeeld de ID van verwerkte events en controleer die voordat een mutatie plaatsvindt. De controle en de daadwerkelijke wijziging moeten waar mogelijk in één database-transactie gebeuren. Anders kan een proces na de wijziging maar vóór het opslaan van de event-ID uitvallen, waarna een herhaling alsnog dezelfde wijziging uitvoert.
Ook de volgorde is niet altijd gegarandeerd. Een melding over een latere status kan eerder arriveren dan een oudere melding, bijvoorbeeld door retries of verschillende verwerkingstijden. Ga dus niet blind uit van de aankomstvolgorde. Gebruik een versienummer, wijzigingstijdstip of actuele status uit de bron om te bepalen of een update nieuwer is. Tijdstempels alleen zijn niet altijd voldoende, bijvoorbeeld wanneer klokken verschillen of meerdere wijzigingen hetzelfde moment krijgen. Bij belangrijke processen kan de ontvanger na een melding de actuele toestand opvragen. Dat kost extra API-verkeer, maar voorkomt dat een vertraagd event de gegevens terugzet naar een oudere status.
Webhooks testen, monitoren en storingen opsporen
Een webhook is pas betrouwbaar als ook de werking ervan zichtbaar is. Registreer per melding een event-ID, ontvangsttijd, resultaat van de handtekeningcontrole, verwerkingstatus en eventuele foutcategorie. Vermijd het loggen van volledige payloads wanneer die persoonsgegevens of geheimen bevatten. Met een correlatie-ID kunnen logs van de verzender, webhookserver en achtergrondtaak aan elkaar worden gekoppeld. Zo is te zien of een melding niet is verzonden, niet is ontvangen of na ontvangst is vastgelopen.
Monitor meer dan alleen of de endpoint-URL bereikbaar is. Belangrijke signalen zijn het aantal mislukte verzoeken, de duur van verwerking, de leeftijd van het oudste bericht in de wachtrij en het aantal retries. Een endpoint kan steeds een succesvolle status teruggeven terwijl de achtergrondverwerking stilvalt. Een groeiende wachtrij of steeds ouder wordende berichten maakt dat probleem eerder zichtbaar. Stel meldingen in op afwijkingen die actie vereisen, niet op iedere losse tijdelijke fout; anders gaan waarschuwingen verloren in ruis.
Test met echte scenario’s, niet alleen met één voorbeeldpayload. Neem ongeldige handtekeningen, dubbele events, ontbrekende velden, vertraagde verwerking en tijdelijke uitval van afhankelijke systemen mee. Controleer ook of retries geen dubbele boekingen veroorzaken. Een testomgeving moet duidelijk gescheiden zijn van productie, zodat testmeldingen geen echte orders of klantgegevens aanpassen. Bewaar daarnaast een procedure voor gecontroleerd opnieuw afspelen van berichten. Dat is handig na een foutieve release, maar kan schade veroorzaken als oude events ongefilterd op een inmiddels gewijzigde applicatie worden losgelaten.
Webhooks inzetten tussen webshop, ERP en voorraadbeheer
In een koppeling tussen webshop en ERP kunnen webhooks verschillende soorten wijzigingen doorgeven. Een webshop kan melden dat een bestelling is geplaatst, terwijl het ERP na verwerking een status- of verzendupdate terugstuurt. Een voorraadplatform kan wijzigingen signaleren aan meerdere verkoopkanalen. Door gebeurtenissen alleen naar relevante systemen te sturen, is minder periodieke controle nodig en kunnen klantinformatie, orderstatus en voorraad sneller worden bijgewerkt.
Toch is een webhook niet hetzelfde als een volledige integratiestrategie. Bepaal per gegeven welk systeem de bron is. Als zowel webshop als ERP voorraad mogen aanpassen, kunnen updates elkaar overschrijven of in een lus terechtkomen. Spreek daarom af welk systeem leidend is voor bijvoorbeeld prijzen, klantgegevens en voorraad, en herken waar mogelijk de oorsprong van een wijziging. Een update die door een koppeling zelf is veroorzaakt, moet niet telkens een nieuwe tegengestelde update terugstarten.
Ook de betekenis van gebeurtenissen moet aansluiten op het bedrijfsproces. Een melding dat een bestelling is aangemaakt betekent niet noodzakelijk dat de betaling rond is of dat de voorraad definitief gereserveerd is. Verwerk die stappen als afzonderlijke gebeurtenissen of controleer de actuele status voordat een vervolgactie plaatsvindt. Bij voorraad is een korte vertraging soms acceptabel, maar tijdens een drukke verkoopactie kan dezelfde vertraging tot oververkoop leiden. In zo’n geval zijn reserveringen, periodieke reconciliatie en duidelijke regels voor gelijktijdige updates belangrijk. De technische keuze voor een webhook moet dus passen bij de gevolgen van een fout in het onderliggende proces.
Wanneer webhooks niet volstaan en een controle nodig blijft
Webhooks zijn geschikt om veranderingen snel te signaleren, maar ze vervangen niet altijd een periodieke controle. De verzender kan tijdelijk uitvallen, een endpoint kan verkeerd geconfigureerd zijn of een bericht kan na alle retries in een aparte foutwachtrij belanden. Zelfs met goede monitoring blijft het verstandig om systemen periodiek met elkaar te vergelijken wanneer ontbrekende gegevens gevolgen hebben voor betaling, voorraad of rapportage.
Een reconciliatie vergelijkt bijvoorbeeld de orders die de webshop als betaald ziet met de betalingen die het boekhoud- of betaalsysteem registreert. De controle hoeft niet ieder detail voortdurend opnieuw te laden. Vaak volstaat het om recente records op status en wijzigingstijdstip te vergelijken, plus af en toe een bredere controle. Let wel op paginering, API-limieten en tijdzones. Een synchronisatie op basis van alleen een tijdstempel kan wijzigingen missen als records exact op de grens vallen of als de bron een update later zichtbaar maakt.
Polling kan ook nodig zijn wanneer een leverancier geen webhooks aanbiedt, gebeurtenissen niet fijnmazig genoeg zijn of wijzigingen uit meerdere bronnen moeten worden samengevoegd. Soms is een hybride aanpak het meest praktisch: een webhook start snelle verwerking, terwijl een geplande taak controleert of de uiteindelijke status overeenkomt. Dat geeft extra zekerheid, maar brengt ook complexiteit en extra verzoeken met zich mee. Leg daarom vast welke bron voorrang krijgt bij een verschil en hoe uitzonderingen worden opgelost. Zonder die afspraak kan een automatische herstelactie juist correcte gegevens overschrijven.