Wat is een webhook?

Je komt webhooks vaak tegen zodra je webshop, betaalprovider, boekhouding of CRM met elkaar moet praten. Het klinkt technischer dan het is. Zie het als een automatisch seintje van systeem A naar systeem B.

Het belangrijke verschil met een gewone API-aanroep: bij een API-aanroep vraag jij iets op. Bij een webhook krijg jij een bericht zodra er iets gebeurt. Dat scheelt onnodig controleren, maar het vraagt wel om een ontvanger die betrouwbaar werkt.

Stel, je hebt een fictieve webwinkel: voorbeeld.nl.

Een klant plaatst een bestelling. Je webshop maakt die bestelling aan. Daarna stuurt de webshop automatisch een webhook naar een URL die jij hebt ingesteld, bijvoorbeeld:

https://voorbeeld.nl/api/webhooks/bestelling

Bij Shopify kan dat bijvoorbeeld via het topic orders/create. Shopify stuurt HTTPS-webhooks als POST-verzoeken naar je endpoint. Je endpoint moet een 2xx HTTP-status teruggeven, anders telt de bezorging niet als succesvol.

Een simpel webhookbericht kan er zo uitzien:

{
  "event": "orders/create",
  "order_id": "abc123",
  "total": "betaald via betaalprovider"
}

In de praktijk wil je daarna vaak nog iets ophalen via een API. Mollie doet dit heel bewust bij klassieke payment webhooks. Mollie stuurt alleen het betalings-ID mee als POST-parameter id. Daarna moet jouw systeem zelf via de Mollie API controleren wat de actuele betaalstatus is.

Dat lijkt omslachtig, maar het is juist verstandig. Een betaalstatus kan veranderen tussen het versturen en ontvangen van de webhook. Verwerk een bestelling daarom niet blind op basis van alleen het webhookbericht.

Een webhook en een API-aanroep zijn familie, maar ze lossen een ander probleem op.

Mijn beslisregel: gebruik een webhook voor het seintje dat er iets is gebeurd. Gebruik een API-aanroep om de actuele details te controleren voordat je iets definitiefs doet.

Wil je eerst de basis van dat tweede deel snappen, lees dan ook wat een API-koppeling is.

Als je webhooks negeert, ga je vaak onnodig pollend werken. Polling betekent dat jouw systeem steeds vraagt: is er al iets nieuws? Dat kan prima zijn bij simpele koppelingen, maar bij bestellingen en betalingen wil je meestal sneller en gerichter reageren.

Andersom is een webhook ook geen magische zekerheid. Een 200- of 2xx-response betekent vooral: technisch ontvangen. Het betekent niet automatisch dat je bestelling inhoudelijk netjes is verwerkt, je voorraad klopt, je mail is verzonden en je boekhouding is bijgewerkt.

Daarom moet je onderscheid maken tussen ontvangen en verwerken. Je webhookontvanger moet snel en correct antwoorden. De echte verwerking mag daarna gecontroleerd gebeuren.

Bij betaaldata of besteldata komt daar nog veiligheid bij. Als een Nederlandse webshop persoonsgegevens van klanten via een webhook naar een externe dienst stuurt die namens de webshop verwerkt, heb je volgens de AVG een verwerkersovereenkomst nodig. Dat is geen technisch detail, maar een praktische randvoorwaarde.

De ontvanger is even down.
Dit is de klassieker. Je webhook-URL geeft geen succesvolle 2xx-status terug. Shopify probeert een mislukte bezorging in totaal 8 keer opnieuw over een periode van 4 uur. Daarna kan de webhooksubscription worden verwijderd. WooCommerce zet een webhook automatisch op disabled na 5 opeenvolgende mislukte bezorgpogingen waarbij de response geen succesvolle 2xx-status is. Stripe probeert mislukte live webhooks automatisch opnieuw te bezorgen met exponential backoff gedurende maximaal 3 dagen.

Je verwerkt dubbele berichten alsof ze nieuw zijn.
Webhooks garanderen meestal niet precies-één-keer verwerking. Door retries kan hetzelfde event nog een keer binnenkomen. Sla daarom op welk event of object je al hebt verwerkt. Werk met object-ID’s, niet met het gevoel dat elk binnenkomend verzoek nieuw zal zijn.

Je vertrouwt op de volgorde van binnenkomst.
Stripe garandeert niet dat webhook-events in dezelfde volgorde aankomen als waarin ze zijn aangemaakt. Dat is belangrijk. Als een betaling en orderupdate kort na elkaar gebeuren, moet jouw systeem niet blind varen op wat als eerste binnenkomt. Controleer de actuele status via de API voordat je een bestelling verwerkt.

Je controleert de afzender niet.
Een webhook zonder handtekeningcontrole of gedeeld geheim is niet veilig genoeg voor bestel- of betaaldata. Shopify adviseert om de X-Shopify-Hmac-Sha256 header te valideren. Daarmee controleert je ontvanger of het verzoek echt van Shopify komt.

• —
  Shopify: werkt met webhooktopics zoals orders/create. Je endpoint krijgt een POST-verzoek en moet een 2xx-status teruggeven. Controleer de HMAC-header.
• —
  WordPress met WooCommerce: WooCommerce stuurt webhooks via HTTP POST naar de ingestelde Delivery URL. Let op mislukte bezorgingen, want na 5 opeenvolgende fouten kan de webhook disabled worden.
• —
  Next.js: hier bouw je meestal zelf de ontvangende URL. De belangrijkste keuze is niet het framework, maar wat je endpoint doet: snel ontvangen, afzender controleren, dubbele verwerking voorkomen en daarna pas de echte actie uitvoeren.

Een webhook is vooral geschikt als startschot. Niet als enige waarheid. Voor bestellingen en betalingen raad ik bijna altijd aan: webhook ontvangen, afzender controleren, actuele status ophalen via API, dan pas verwerken.

Werk je aan koppelingen tussen webshop, betaalprovider, voorraad of administratie, dan valt dit onder automatisering voor MKB. REBUS Digital Solutions helpt ook met automatisering en koppelingen als je wilt dat dit netjes wordt uitgezocht en gebouwd.