Wat is een webhook?

Een webhook in twee zinnen

Een webhook is een HTTP-verzoek dat systeem A naar een vast adres van systeem B stuurt zodra er in A iets gebeurt. Bij een API koppeling stelt jouw kant de vraag; bij een webhook meldt de andere kant zich.

Je stelt een webhook in door per gebeurtenis een adres op te geven. In Shopify heet zo'n gebeurtenis een topic, bijvoorbeeld orders/create of inventory_levels/update. In WooCommerce is het order.created, in Picqer orders.created of products.free_stock_changed.

Dit is het bericht dat Shopify verstuurt wanneer Bakker Installatie B.V. een bestelling plaatst:

POST /webhooks/shopify HTTP/1.1
Host: koppeling.example.nl
Content-Type: application/json
X-Shopify-Topic: orders/create
X-Shopify-Webhook-Id: b54557e4-bdd9-4b37-8a5f-bf7d70bcd043
X-Shopify-Triggered-At: 2026-10-02T09:04:11.153Z
X-Shopify-Hmac-Sha256: XWmrwMey6OsLMeiZKwP4FppHH3cmAiiJJAweH5Jo4bM=

{
  "id": 5804812345601,
  "name": "#10482",
  "email": "inkoop@bakkerinstallatie.example",
  "total_price": "248.00",
  "currency": "EUR",
  "line_items": [
    { "sku": "KB-2210", "quantity": 12, "price": "17.08" }
  ]
}

Drie regels in de kop van dat bericht zijn voor de koppeling net zo belangrijk als de order zelf. X-Shopify-Webhook-Id is het unieke nummer van dit bericht. X-Shopify-Triggered-At is het moment van de gebeurtenis. X-Shopify-Hmac-Sha256 is de handtekening waarmee de ontvanger controleert dat het bericht van Shopify komt. Alle drie komen hieronder terug.

Webhook of steeds opnieuw vragen (polling)?

Zonder webhook is er één manier om wijzigingen te zien: op vaste momenten vragen wat er veranderd is. Dat heet polling. Het werkt bij elk systeem met een API en het kost twee dingen: wachttijd en verzoeken.

Een rekenvoorbeeld met een webshop die 40 orders per dag krijgt:

Een dag heeft 96 kwartieren, dus 96 rondes. Bij 40 orders leveren minstens 56 van die 96 verzoeken een leeg antwoord op. Die lege verzoeken tellen wel mee voor de rate limit van het systeem. Vaker vragen verkort de wachttijd en verhoogt het aantal lege verzoeken: bij elke 5 minuten zijn het er 288 per dag, waarvan minstens 248 zonder resultaat.

Bij voorraad loopt het verschil verder op. Er zijn standaardkoppelingen die voorraad scannen in porties van 10 producten per 5 minuten. Dat is 120 producten per uur. Een assortiment van 1.000 producten kost dan 100 porties van 5 minuten: 500 minuten, ofwel 8 uur en 20 minuten voor één volledige ronde. Een voorraadwijziging van 09:00 staat in het slechtste geval pas na 17:00 in de webshop. Voor orders bestaan er standaardkoppelingen die nieuwe bestellingen zonder webhook eens per uur ophalen en met webhook direct.

Polling blijft de juiste keuze voor gegevens waar niemand op wacht. Grootboekregels of een prijslijst gaan in één nachtelijke ronde, en die ronde is in één keer te controleren. Welke stroom welke snelheid nodig heeft staat in realtime of batch. Hoe je uitrekent hoe lang een ronde duurt staat in doorvoer berekenen.

Waarom een webhook geen garantie is

Een webhook wordt minstens één keer afgeleverd. Dat is iets anders dan precies één keer, en over de volgorde wordt niets beloofd. Shopify schrijft in de documentatie voor ontwikkelaars dat aflevering niet altijd gegarandeerd is, dat de volgorde niet vastligt en dat hetzelfde bericht vaker dan één keer kan aankomen. Vier dingen gaan in de praktijk mis.

Hetzelfde bericht komt twee keer aan

Shopify wacht 5 seconden op een antwoord. Komt er in die tijd geen 200 OK, dan telt de aflevering als mislukt en volgt een nieuwe poging, ook als de ontvanger het eerste bericht al verwerkt heeft. Een koppeling die de order eerst in het ERP aanmaakt en daarna pas antwoordt, komt bij een traag ERP boven die 5 seconden uit. Het gevolg: twee verkooporders voor één bestelling.

De oplossing heeft twee delen. De ontvanger zet het bericht in een wachtrij en antwoordt direct, zodat het antwoord binnen milliseconden terug is en het verwerken daarna gebeurt. En de koppeling bewaart het X-Shopify-Webhook-Id van elk verwerkt bericht, zodat een bericht dat voor de tweede of derde keer binnenkomt wordt overgeslagen. Waar dubbele orders en dubbele debiteuren verder vandaan komen staat in dubbele klanten en debiteuren.

Berichten komen in de verkeerde volgorde aan

Een klant plaatst een order en past een minuut later het afleveradres aan. Shopify verstuurt orders/create en orders/updated en garandeert niet dat ze in die volgorde aankomen. Verwerkt de koppeling ze op volgorde van binnenkomst, dan overschrijft het oude adres het nieuwe. De koppeling vergelijkt daarom het tijdstip van de gebeurtenis (X-Shopify-Triggered-At, of het veld updated_at in de order) met wat al verwerkt is, en slaat een bericht over dat ouder is dan de stand in het ERP.

Een bericht komt helemaal niet aan

Na een mislukte aflevering probeert Shopify het 8 keer opnieuw, verspreid over 4 uur. Mislukken 8 pogingen op rij, dan verwijdert Shopify het abonnement als het via de Admin API is aangemaakt. Staat de ontvangende kant een middag van 5 uur stil, dan zijn de berichten van die middag weg en komen er daarna ook geen nieuwe meer. De enige waarschuwing is een e-mail van Shopify aan het noodadres van de ontwikkelaar van de app.

WooCommerce schakelt een webhook uit na meer dan 5 mislukte afleveringen op rij; alles behalve een antwoord met status 2xx, 301 of 302 telt als mislukt. Picqer probeert het volgens de eigen documentatie 15 keer in ongeveer 17 uur en deactiveert een webhook na 5 volledig mislukte berichten binnen 24 uur.

Het bericht komt te vroeg

Een webhook gaat uit op het moment van de gebeurtenis. Een app voor fraudecontrole die de order 30 seconden later een label of een risicoscore geeft, komt daarna. De koppeling heeft de eerste versie dan al doorgezet, zonder dat label. Hangt de verwerking van zulke gegevens af, dan verwerkt de koppeling de order met een korte vertraging of luistert hij ook naar orders/updated.

De controleronde vangt op wat de webhook mist

Naast elke webhook hoort daarom een controleronde: een geplande vraag aan de API, bijvoorbeeld elk uur, naar alles wat sinds de vorige ronde is gewijzigd. Dat zijn 24 verzoeken per dag in plaats van 96 of 288, en ze vinden de order terug waarvan het bericht nooit aankwam. Shopify raadt dit zelf aan en noemt het een reconciliation job. De webhook levert de snelheid, de controleronde de volledigheid. Wat er verder gebeurt als een van beide kanten stilstaat, staat in wat gebeurt er als een koppeling uitvalt.

Welke systemen hebben webhooks?

De regels verschillen per systeem. Deze zijn op 3 oktober 2026 nagelezen in de documentatie van de leverancier.

De tweede kolom bepaalt hoeveel werk een webhook bespaart. Shopify, WooCommerce en Picqer sturen de gegevens mee. Exact Online en Business Central melden alleen welk record is gewijzigd, niet wat er gewijzigd is. Zo ziet een melding van Business Central eruit:

{
  "value": [
    {
      "subscriptionId": "webhookItemsId",
      "resource": "api/v2.0/companies(b18aed47-c385-49d2-b954-dbdf8ad71780)/items(26814998-936a-401c-81c1-0e848a64971d)",
      "changeType": "updated",
      "lastModifiedDateTime": "2026-10-02T09:04:20.467Z"
    }
  ]
}

Er staat geen voorraad, prijs of omschrijving in. De koppeling haalt het artikel daarna zelf op, en dat verzoek telt mee voor de limiet van de API. Bij Exact Online is die limiet 60 verzoeken per minuut en 5.000 per dag per administratie. 300 voorraadwijzigingen op een dag zijn 300 meldingen plus 300 verzoeken: 6% van het dagbudget. Een import van 2.000 artikelen in één keer levert 2.000 meldingen op. Met 60 verzoeken per minuut duurt het ophalen daarvan ruim 33 minuten en kost het 40% van het dagbudget. De rekensom per abonnement staat in Exact Online API limieten.

Exact Online heeft webhooks voor een vaste lijst onderwerpen, waaronder Accounts, Items, StockPositions en GoodsDeliveries. Het bericht bevat naast de verwijzing een ExactOnlineEndpoint: het adres waar de koppeling het gewijzigde record ophaalt.

Business Central heeft twee eigen regels, beschreven in de documentatie van Microsoft. Een abonnement verloopt na 3 dagen en moet voor die tijd verlengd worden, anders stoppen de meldingen. En Business Central wacht standaard 30 seconden na de eerste wijziging voordat de melding uitgaat. Veranderen er in die 30 seconden meer dan 1.000 records, dan komt er één verzamelmelding (changeType: collection) in plaats van een melding per record.

Systemen met webhooks hebben ze zelden voor alles. Voor wat ontbreekt blijft polling over, of een feed die op vaste tijden klaarstaat.

Wat betekent dit voor je koppeling?

Een webhook instellen is één scherm in de beheeromgeving van je webshop. Het werk zit in wat erachter staat: een ontvanger die de handtekening controleert en binnen de limiet antwoordt, een wachtrij, een controle op dubbele berichten en een controleronde voor wat niet aankwam. Dat bouwen wij als onderdeel van de koppeling, en daarna draaien en bewaken we het. In het dashboard met logs zie je wat er is binnengekomen en wat ermee gedaan is.

Welke stroom via webhooks loopt en welke in een geplande ronde, wordt per stroom vastgelegd. Het overzicht van alle stromen staat op koppelingen tussen je webshop en de systemen erachter. Voor bestellingen is dat orders, klanten en verzending, voor voorraad voorraad en beschikbaarheid. Vertel welke systemen je gebruikt, dan hoor je welke daarvan webhooks hebben en waar een ronde nodig is.