Webhooks: Hoe real-time gegevensuitwisseling tussen systemen werkt

Webhooks: hoe real-time gegevensuitwisseling tussen systemen werkt

Webhooks zijn geautomatiseerde HTTP-berichten die een systeem naar een ander systeem stuurt zodra een bepaalde gebeurtenis plaatsvindt. Waar een gewone API-koppeling vraagt om gegevens, sturen webhooks die gegevens zelf op het juiste moment. Dit maakt ze geschikt voor elke applicatie die direct moet reageren op veranderingen, zonder voortdurend te pollen.

Wat zijn webhooks precies?

Een webhook is een HTTP-callback: een geautomatiseerd bericht dat van systeem A naar systeem B gaat op het moment dat er iets gebeurt. Denk aan een betaling die slaagt, een formulier dat wordt ingediend of een bestelling die van status wisselt. Het ontvangende systeem hoeft niets te vragen, het krijgt de melding direct toegestuurd.

Een webhook is een eindpunt-URL die luistert naar inkomende POST-verzoeken met gestructureerde gegevens, doorgaans in JSON-formaat. Het verzendende systeem roept die URL aan zodra de triggergebeurtenis zich voordoet. Zo verloopt communicatie tussen systemen zonder dat er constant een verbinding open hoeft te blijven.

Een webshop die 500 bestellingen per dag verwerkt, kan met webhooks automatisch een factuur aanmaken, een magazijnpicker aansturen en een klant een bevestigingsmail sturen, allemaal binnen enkele seconden na de bestelling. Handmatige tussenkomst is dan niet meer nodig.

Hoe webhooks werken

Het werkingsprincipe is eenvoudig: het verzendende systeem heeft een configuratiescherm waarin je een URL opgeeft en aangeeft bij welke gebeurtenissen het een bericht moet sturen. Zodra die gebeurtenis optreedt, verstuurt het systeem een HTTP POST-verzoek naar jouw URL met alle relevante data.

1. Je registreert een webhook-URL in het externe systeem, bijvoorbeeld Stripe of Shopify.
2. Het externe systeem slaat die URL op en koppelt hem aan één of meerdere gebeurtenissen.
3. Wanneer de gebeurtenis plaatsvindt, stuurt het systeem een POST-verzoek met een JSON-payload naar jouw URL.
4. Jouw server ontvangt het verzoek, verwerkt de data en stuurt een HTTP 200-statuscode terug als bevestiging.
5. Als die bevestiging uitblijft, probeert het externe systeem de webhook opnieuw te verzenden, vaak tot drie keer met toenemende tussenpozen.

Webhook-systemen verwachten binnen 5 tot 30 seconden een reactie. Duurt de verwerking langer, bevestig het verzoek dan direct en handel de verwerking asynchroon af via een wachtrij. Dit is een detail dat in de praktijk veel problemen voorkomt.

Webhooks vs API's: wat is het verschil?

Webhooks en API's zijn complementair. Het verschil zit in de richting van het initiatief. Bij een API roept jouw systeem het andere systeem aan om data op te halen. Bij een webhook roept het andere systeem jóuw systeem aan omdat er iets is veranderd.

Kenmerk	REST API (polling)	Webhook (push)
Initiatief	Jouw systeem vraagt	Extern systeem stuurt
Timing	Op vaste intervallen	Direct bij gebeurtenis
Serverbelasting	Hoog bij hoge frequentie	Laag, alleen bij events
Complexiteit setup	Lager	Iets hoger
Realtime	Nee	Ja

Polling elke minuut op een druk platform levert al snel 1.440 API-aanroepen per dag op, ook als er niets is veranderd. Webhooks sturen alleen een bericht als er iets gebeurt, wat in veel scenario's 90% minder aanroepen oplevert. Voor onze integratiediensten kiezen we standaard voor webhooks zodra het externe systeem ze ondersteunt.

Praktische voorbeelden van webhooks

Webhooks worden breed ingezet, van betaalplatforms tot CRM-systemen. Enkele concrete toepassingen waar wij dagelijks mee werken:

• Betalingsverwerking: Stripe stuurt een webhook bij een geslaagde of mislukte betaling, waarna een abonnement direct wordt geactiveerd of een factuur als betaald wordt gemarkeerd.
• E-commerce: Shopify verstuurt webhooks bij nieuwe bestellingen, retourzendingen en voorraadwijzigingen, zodat een ERP-systeem altijd actuele data heeft.
• CRM-automatisering: Wanneer een lead in HubSpot een bepaalde score bereikt, triggert een webhook een taak in het planningssysteem van de salesafdeling.
• CI/CD-pipelines: GitHub stuurt een webhook bij elke push naar de main-branch, wat automatisch een bouwproces en deployment start.
• Zorgapplicaties: Een patiëntportaal meldt via een webhook aan een achtergrondsysteem wanneer een patiënt een afspraak bevestigt, zonder dat een medewerker dit handmatig hoeft door te geven.

Dit soort koppelingen bouwen we ook voor klanten die hun API-integratie willen laten bouwen. Webhooks zijn daarin vaak de snelste route naar real-time synchronisatie.

Implementatie en setup van webhooks

Een webhook opzetten vraagt om een publiek bereikbaar eindpunt op jouw server. Lokale ontwikkeling doe je met tools als ngrok, die een tijdelijke publieke URL aanmaken voor jouw localhost-omgeving. In productie gebruik je een vast HTTPS-eindpunt, want HTTP wordt door de meeste platformen geweigerd.

Bij het bouwen van applicaties met webhook-ondersteuning houden we altijd rekening met idempotentie: als dezelfde webhook twee keer binnenkomt, mag de verwerking maar één keer plaatsvinden. Sla de unieke webhook-ID op en sla dubbele verzoeken over. Stripe vermeldt in zijn documentatie dat duplicaten bij netverlies regelmatig voorkomen.

Voor complexere applicaties, zoals onze projecten in web development, verwerken we webhooks via een berichtenwachtrij zoals RabbitMQ of een managed service als AWS SQS. Dit vangt piekbelasting op en garandeert dat geen enkel bericht verloren gaat, ook niet als de verwerkende service even offline is.

Beveiliging en best practices

Een webhook-eindpunt dat open op het internet staat, is een potentieel aanvalsoppervlak. Elke inkomende POST kan in theorie van een kwaadwillende partij komen. De meeste platforms lossen dit op met een gedeeld geheim: ze sturen een HMAC-handtekening mee in de header, die jouw server verifieert voordat de payload wordt verwerkt.

• Valideer de handtekening altijd voordat je de payload verwerkt, niet erna.
• Gebruik HTTPS op het ontvangende eindpunt, zonder uitzondering.
• Beperk de payload-grootte om denial-of-service via oversized verzoeken te voorkomen.
• Log elke binnenkomende webhook met tijdstempel en unieke ID voor debugging en auditing.
• Stel timeouts in op de verwerkende code om te voorkomen dat een trage bewerking het eindpunt blokkeert.
• Monitor op mislukte bezorgingen via het dashboard van het externe systeem en stel alerts in.

Sla de ruwe webhook-payload altijd op voordat je hem verwerkt. Als de verwerking later faalt door een bug, kun je de originele payload opnieuw door de verwerkingspijplijn sturen zonder het externe systeem opnieuw aan te roepen. Dit bespaart in productie-incidenten veel tijd. Wil je weten hoe wij dit aanpakken? Bekijk dan onze AI-oplossingen of neem contact op voor een adviesgesprek.

Veelgestelde vragen over webhooks

Wat is het verschil tussen een webhook en een API-aanroep?

Bij een API-aanroep vraagt jouw systeem actief om data bij een extern systeem. Een webhook werkt omgekeerd: het externe systeem stuurt automatisch data naar jouw systeem zodra een gebeurtenis plaatsvindt. API-aanroepen zijn geschikt voor het op aanvraag opvragen van data. Webhooks zijn geschikt voor real-time meldingen, verlagen de serverbelasting en zorgen voor snellere reactietijden omdat er geen periodieke polling nodig is.

Hoe test ik een webhook lokaal?

Lokaal testen doe je met een tool als ngrok of Cloudflare Tunnel. Die maken een tijdelijke publieke URL aan die al het verkeer doorstuurt naar jouw lokale server. Platforms zoals Stripe en GitHub hebben ook een ingebouwde testomgeving waarmee je voorbeeldpayloads naar jouw eindpunt kunt sturen zonder een echte gebeurtenis te triggeren. Dit verkort de ontwikkelcyclus aanzienlijk.

Wat gebeurt er als mijn server de webhook niet ontvangt?

De meeste webhook-platforms proberen een mislukte bezorging automatisch opnieuw. Stripe probeert het tot 72 uur lang met toenemende intervallen, GitHub probeert het drie keer. Als alle pogingen mislukken, markeert het platform de webhook als mislukt en kun je een handmatige herbezorging starten via het dashboard. Stel daarom altijd een monitoring-alert in als jouw eindpunt meerdere mislukte bezorgingen op rij ontvangt.

Zijn webhooks geschikt voor elke applicatie?

Niet altijd. Webhooks werken het best als het externe systeem ze native ondersteunt en jouw eindpunt stabiel en publiek bereikbaar is. Voor interne systemen achter een bedrijfsfirewall, of voor toepassingen waarbij de volgorde van berichten cruciaal is, is een combinatie van webhooks met een berichtenwachtrij verstandiger. Bij lage frequentie en eenvoudige data-uitwisseling kan een geplande API-aanroep voldoende zijn.