Hoe werkt een webhook: De complete uitleg voor developers en bedrijven

Hoe werkt een webhook: de complete uitleg voor developers en bedrijven

Een webhook is een automatische HTTP-melding die één systeem naar een ander stuurt op het moment dat een specifieke gebeurtenis plaatsvindt. In plaats van continu te vragen "is er al iets veranderd?", stuurt het bronsysteem zelf een datapakket zodra er actie nodig is. Dit maakt webhooks snel en geschikt voor realtime koppelingen tussen applicaties.

Webhooks versus polling: een helder verschil

Webhooks zijn het tegenovergestelde van polling. Bij polling stuurt jouw applicatie elke paar seconden of minuten een verzoek naar een externe dienst om te controleren of er nieuwe data is. Bij een webhook draait die communicatie om: de externe dienst neemt zelf het initiatief en stuurt een bericht zodra er iets verandert.

Wanneer een webshop 10.000 bestellingen per dag verwerkt, veroorzaakt polling tot 86.400 onnodige API-verzoeken per dag bij een polling-interval van 10 seconden. Met webhooks daalt dat aantal naar precies 10.000 verzoeken, één per bestelling. Dat scheelt direct in serverkosten en verwerkingstijd.

Hoe werkt een webhook technisch gezien?

Een webhook werkt op basis van vier stappen: registratie, event, verzending en verwerking. Zodra je begrijpt hoe deze stappen samenhangen, snap je ook waarom webhooks zo gangbaar zijn in systeemkoppelingen.

1. Registratie: Jij geeft bij de externe dienst een URL op, de webhook endpoint. Dit is het adres van jouw server dat berichten ontvangt.
2. Event: Er vindt een actie plaats in het bronsysteem, zoals een nieuwe betaling, een formulierinzending of een statuswijziging.
3. Verzending: Het bronsysteem stuurt automatisch een HTTP POST-verzoek naar jouw opgegeven URL. Dit verzoek bevat een JSON-payload met alle relevante data over het event.
4. Verwerking: Jouw server ontvangt de payload, verwerkt de gegevens en stuurt een HTTP 200-statuscode terug als bevestiging. Zonder die bevestiging beschouwt het bronsysteem de aflevering als mislukt.

In de praktijk: een klant doet een betaling via Mollie. Mollie stuurt direct na succesvolle verwerking een POST-verzoek naar jouw webhook endpoint met het betalingsnummer, het bedrag en de status. Jouw systeem werkt de bestelling bij, stuurt een bevestigingsmail en activeert eventueel een vervolgproces. Alles automatisch, binnen milliseconden.

Veelgebruikte toepassingen van webhooks

Webhooks zijn toepasbaar in vrijwel elke sector waar systemen realtime met elkaar moeten communiceren. Dit zijn de meest voorkomende use cases.

• Betalingsverwerking: Betaaldiensten zoals Stripe, Mollie en PayPal gebruiken webhooks om betalingsstatus direct door te sturen. Vertraging van meer dan 2 seconden in betalingsbevestiging verhoogt het klantverloop met gemiddeld 40%.
• E-commerce en voorraadbeheer: Wanneer een bestelling wordt geplaatst, triggert een webhook direct een update in het magazijnsysteem, de boekhoudsoftware en het bezorgsysteem.
• CI/CD pipelines: GitHub en GitLab sturen webhooks na elke code-push, waardoor een automatische build en deployment start zonder handmatige tussenkomst.
• CRM-integraties: Wanneer een lead een contactformulier invult, stuurt de website een webhook naar het CRM zodat de salesmedewerker direct een notificatie ontvangt.
• Zorg en overheid: Systemen in de zorgsector gebruiken webhooks om patiëntstatussen, afspraakbevestigingen en medicatiemeldingen realtime te synchroniseren tussen applicaties.

Voor bedrijven die hun systemen willen verbinden, bieden onze integraties diensten een directe oplossing. We bouwen koppelingen die betrouwbaar werken op schaal, ongeacht het aantal dagelijkse events.

Beveiliging van webhooks: wat je niet mag overslaan

Een webhook-endpoint is technisch gezien een open poort naar jouw server. Elke buitenstaander die de URL kent, kan in theorie verzoeken sturen. Goede beveiliging is daarom geen optie, maar een vereiste.

• Handtekeningvalidatie: Het bronsysteem stuurt een HMAC-handtekening mee in de header. Jouw server berekent dezelfde handtekening op basis van de gedeelde geheime sleutel en vergelijkt beide. Komen ze niet overeen, dan wordt het verzoek geweigerd.
• HTTPS verplicht: Verwerk webhooks altijd over een versleutelde verbinding. Een onbeveiligd HTTP-endpoint is kwetsbaar voor man-in-the-middle-aanvallen.
• IP-whitelisting: Grote diensten publiceren de IP-adressen van hun webhook-servers. Door alleen die adressen toe te staan, blokkeer je ongewenste verzoeken al op netwerkniveau.
• Idempotency: Een webhook kan soms twee keer worden afgeleverd. Zorg dat je server dubbele verwerking herkent en overslaat op basis van een unieke event-ID.

Error handling en retry logic bij webhooks

Wanneer een webhook-endpoint tijdelijk niet bereikbaar is, gooit een goed ingericht bronsysteem het bericht niet weg. Het start een retry-cyclus. Stripe hanteert 7 pogingen over 72 uur, met oplopende intervallen tussen elke poging.

Als jouw server een andere statuscode dan 200 teruggeeft, of als er geen antwoord komt binnen de timeout van gemiddeld 5 tot 30 seconden, registreert het bronsysteem een mislukking. Verwerk de webhook daarom asynchroon: ontvang het bericht, stuur direct een 200-antwoord terug en verwerk de data daarna in een achtergrondwachtrij. Zo voorkom je timeouts bij zware verwerkingsoperaties.

Debuggen en testen van webhooks

Webhooks testen is lastiger dan gewone API-aanroepen, want de trigger ligt bij een extern systeem. Er zijn gelukkig betrouwbare methoden om dit lokaal en in productie te doen.

Tools zoals ngrok maken een tijdelijke publieke URL aan die doorverwijst naar jouw localhost. Zo ontvang je echte webhook-verzoeken op jouw ontwikkelomgeving zonder een server te deployen. Stripe en GitHub bieden bovendien ingebouwde dashboard-functies waarmee je eerder verzonden webhook-events opnieuw kunt versturen, wat het debuggen van specifieke foutscenario's aanzienlijk eenvoudiger maakt.

Teams die een speciale webhook-loggingtabel bijhouden, lossen bugs gemiddeld 3 keer sneller op dan teams die dat niet doen. Sla elke inkomende payload op met timestamp, statuscode en eventuele foutmelding. Die data is onmisbaar bij incidentonderzoek.

Voor complexe applicaties waarbij webhooks de kern vormen van de data-uitwisseling, bouwen we bij Score Agency schaalbare webapplicaties met ingebouwde event-verwerkingsarchitectuur. Naast webhooks werken we ook met slimme automatiseringsoplossingen die events intelligent verwerken en routeren op basis van context.

Veelgestelde vragen over webhooks

Hoe werkt een webhook anders dan een REST API?

Een REST API werkt op aanvraag: jouw applicatie stuurt een verzoek en wacht op een antwoord. Een webhook werkt omgekeerd: het bronsysteem stuurt automatisch een bericht op het moment dat een event plaatsvindt, zonder dat jij hoeft te pollen. REST API's zijn geschikt voor data ophalen wanneer jouw systeem daar behoefte aan heeft. Webhooks zijn geschikt voor realtime notificaties. In veel systemen worden beide gecombineerd voor een complete integratie.

Wat gebeurt er als mijn server de webhook niet ontvangt?

Als jouw endpoint niet reageert of een foutcode teruggeeft, probeert het bronsysteem de webhook automatisch opnieuw te versturen. Stripe voert 7 pogingen uit over 72 uur, terwijl GitHub na 3 mislukte pogingen stopt. Stel een monitoring-systeem in dat je waarschuwt zodra het retrypercentage boven 5% stijgt.

Is een webhook veilig te gebruiken zonder extra maatregelen?

Nee. Een webhook-endpoint zonder beveiligingsmaatregelen is kwetsbaar voor ongewenste of kwaadaardige verzoeken. Je hebt minimaal HMAC-handtekeningvalidatie en HTTPS nodig. Afhankelijk van de gevoeligheid van de data voeg je IP-whitelisting en idempotency-controles toe. Bedrijven die persoonsgegevens verwerken via webhooks, moeten daarnaast rekening houden met AVG-verplichtingen rondom datadoorgifte.

Kan ik webhooks ook zelf versturen vanuit mijn applicatie?

Ja. Wanneer jouw platform andere systemen moet informeren over events, kun je zelf een webhook-dienst bouwen. Jouw applicatie stuurt dan POST-verzoeken naar externe endpoints die klanten of partners hebben opgegeven. Platforms zoals Shopify en WooCommerce werken op deze manier. Jij bent dan de zender in plaats van de ontvanger. De technische opzet vereist een betrouwbare wachtrij voor retry-logica en gedetailleerde logging van alle pogingen.

Voor welke sectoren zijn webhooks het meest geschikt?

Webhooks leveren de meeste waarde in sectoren waar realtime datasynchronisatie kritisch is: e-commerce, financiële dienstverlening, de zorgsector en logistiek. In de zorg synchroniseren webhooks patiëntgegevens tussen ziekenhuissystemen en externe zorgverleners zonder handmatige handelingen. Ook voor overheidsorganisaties die meerdere registratiesystemen koppelen, zijn webhooks een betrouwbare keuze. Neem contact op als je wilt weten wat de beste aanpak is voor jouw situatie.