Wat is een webhook? – Werking en voorbeelden

Een webhook is een manier waarop een applicatie automatisch gegevens naar een andere applicatie stuurt zodra een bepaalde gebeurtenis plaatsvindt. Het ontvangende systeem hoeft daardoor niet steeds zelf te controleren of er nieuwe informatie beschikbaar is.

Een betaalprovider kan bijvoorbeeld direct een bericht naar een webshop sturen zodra een betaling is geslaagd. De webshop weet hierdoor vrijwel meteen dat de bestelling verder verwerkt kan worden.

Wat is een webhook?

Een webhook is een automatische melding tussen twee softwaresystemen. Je stelt vooraf in naar welk webadres informatie moet worden gestuurd wanneer een bepaalde gebeurtenis plaatsvindt.

Zo’n gebeurtenis wordt vaak een event genoemd. Denk aan een succesvolle betaling, nieuwe bestelling, gewijzigde klant of afgeronde verzending.

Het systeem waarin de gebeurtenis plaatsvindt, verstuurt vervolgens automatisch gegevens naar het ontvangende systeem. Dit gebeurt meestal via een HTTP-request naar een speciaal daarvoor ingesteld URL-adres.

Hoe werkt een webhook?

Een webhook werkt op basis van gebeurtenissen. Systeem A wacht totdat een vooraf bepaalde gebeurtenis plaatsvindt en stuurt daarna automatisch informatie naar systeem B.

Bij een online betaling kan dat bijvoorbeeld zo werken:

1. Een klant rondt de betaling af.
2. De betaalprovider registreert de betaling.
3. De gebeurtenis betaling geslaagd wordt geactiveerd.
4. De betaalprovider verstuurt een webhook.
5. De webshop ontvangt de betaalgegevens.
6. De bestelling krijgt automatisch de status betaald.

Het belangrijkste is dat de webshop niet steeds opnieuw hoeft te vragen of de betaling al binnen is. De betaalprovider stuurt de informatie zelf zodra er iets verandert.

Voorbeeld van een webhook

Stel dat een klant om 14:32 uur een bestelling betaalt. De webshop weet op dat moment nog niet automatisch dat de betaling succesvol is afgerond.

De betaalprovider kan vervolgens een webhook naar een vooraf ingesteld adres van de webshop sturen. In het bericht kunnen bijvoorbeeld het bestelnummer, bedrag en de betaalstatus staan.

Een sterk vereenvoudigd voorbeeld kan er zo uitzien:

{
  "bestelling": "12345",
  "bedrag": 129.00,
  "status": "betaald"
}

De webshop verwerkt deze informatie en verandert bestelling 12345 automatisch naar betaald. Daarna kan bijvoorbeeld het magazijnproces worden gestart of een bevestigingsmail worden verzonden.

Wat is een webhook URL?

Een webhook URL is het adres waarnaar een ander systeem de webhook verstuurt. Het ontvangende systeem moet op dit adres klaarstaan om binnenkomende berichten te verwerken.

Een fictieve webhook URL kan er bijvoorbeeld zo uitzien:

Je geeft deze URL vervolgens door aan de software die de webhook moet versturen. Bij sommige diensten kun je dit zelf instellen via het dashboard of de ontwikkelaarsinstellingen.

Welke informatie naar deze URL wordt gestuurd, verschilt per dienst. In de documentatie staat normaal beschreven welke gebeurtenissen beschikbaar zijn en hoe de gegevens zijn opgebouwd.

Wat is het verschil tussen een webhook en API?

Een API en webhook kunnen beide systemen met elkaar laten communiceren, maar het initiatief ligt anders. Bij een normale API-request vraagt een applicatie zelf om informatie.

Bij een webhook stuurt het andere systeem juist automatisch informatie zodra een gebeurtenis plaatsvindt. Je hoeft dus niet voortdurend te vragen of er iets is veranderd.

Wil je eerst begrijpen hoe API’s werken? Lees dan onze uitleg over wat een API is.

Een praktisch verschil tussen API en webhook

Stel dat een webshop wil weten of een betaling is geslaagd. Zonder webhook zou de webshop bijvoorbeeld regelmatig via een API kunnen vragen: “Is bestelling 12345 al betaald?”

Als dit iedere tien seconden gebeurt, worden veel verzoeken verstuurd terwijl er misschien niets veranderd is. Dit principe van regelmatig opnieuw controleren wordt vaak polling genoemd.

Met een webhook hoeft dat niet. De betaalprovider stuurt zelf een bericht zodra de betaling succesvol is, waardoor de webshop alleen informatie ontvangt wanneer er daadwerkelijk iets gebeurt.

API en webhook kunnen samenwerken

Een webhook is niet simpelweg een vervanging voor een API. Binnen dezelfde API koppeling kunnen beide technieken naast elkaar worden gebruikt.

Een webhook kan bijvoorbeeld melden dat een nieuwe bestelling is geplaatst. De ontvangende applicatie kan daarna via een API aanvullende informatie over die bestelling ophalen.

De webhook zorgt dan voor het signaal dat er iets is gebeurd. De API wordt vervolgens gebruikt om aanvullende gegevens op te vragen of een actie uit te voeren.

Waarvoor worden webhooks gebruikt?

Webhooks zijn vooral handig wanneer een systeem snel moet reageren op een gebeurtenis. Je komt ze daarom bij veel verschillende soorten zakelijke software tegen.

Voorbeelden zijn:

Welke gebeurtenissen beschikbaar zijn, hangt af van de software. Sommige platforms bieden tientallen verschillende webhook-events aan.

Wat gebeurt er als een webhook niet aankomt?

Een webhook kan mislukken wanneer het ontvangende systeem tijdelijk niet bereikbaar is. Ook een verkeerde webhook URL, serverfout of technisch probleem kan ervoor zorgen dat een bericht niet goed wordt verwerkt.

Veel professionele systemen proberen een mislukte webhook daarom later opnieuw te versturen. Dit wordt vaak een retry genoemd.

Hoe vaak dat gebeurt en hoeveel tijd ertussen zit, verschilt per aanbieder. Controleer daarom de documentatie wanneer een webhook belangrijk is voor een bedrijfsproces.

Kan een webhook dubbel binnenkomen?

Ja, daar moet je bij het bouwen van een webhookintegratie rekening mee houden. Een verzendend systeem kan hetzelfde event in sommige situaties meer dan één keer versturen, bijvoorbeeld door een retry.

Het ontvangende systeem moet daarom voorkomen dat hetzelfde bericht twee keer tot dezelfde actie leidt. Een dubbele webhook voor een betaling mag bijvoorbeeld niet betekenen dat een bestelling twee keer wordt verwerkt.

Ontwikkelaars kunnen hiervoor unieke event- of transactienummers gebruiken. Zo kan het systeem herkennen dat een bepaalde gebeurtenis al eerder is verwerkt.

Zijn webhooks veilig?

Webhooks kunnen bedrijfs- of klantgegevens bevatten en moeten daarom veilig worden ingericht. Een ontvangend systeem moet niet zomaar ieder binnenkomend verzoek vertrouwen.

Veel aanbieders gebruiken daarom een handtekening, token of andere methode waarmee het ontvangende systeem kan controleren of een webhook echt van de verwachte afzender afkomstig is.

Gebruik daarnaast een beveiligde HTTPS-verbinding en controleer de documentatie van de aanbieder. Welke beveiligingsmethode nodig is, verschilt namelijk per dienst.

Webhook en API key

Een webhook hoeft niet automatisch met een API key te werken. De methode waarmee een webhook wordt beveiligd wordt bepaald door de verzendende dienst.

Sommige aanbieders gebruiken bijvoorbeeld een geheime sleutel om een digitale handtekening te maken. Het ontvangende systeem kan daarmee controleren of de inhoud onderweg niet is aangepast en van de juiste afzender komt.

Een API key wordt vaker gebruikt bij verzoeken naar een API. In onze uitleg over wat een API key is lees je hoe zo’n sleutel werkt.

Hoe stel je een webhook in?

De precieze stappen verschillen per softwarepakket. Meestal begin je met het aanmaken van een endpoint in het systeem dat de webhook moet ontvangen.

Daarna voer je de bijbehorende webhook URL in bij de verzendende dienst. Vervolgens kies je voor welke gebeurtenissen je meldingen wilt ontvangen.

Een eenvoudige inrichting bestaat meestal uit:

1. webhook endpoint maken;
2. webhook URL invoeren;
3. gewenste events selecteren;
4. beveiliging instellen;
5. testbericht versturen;
6. controleren of gegevens goed worden verwerkt.

Veel softwareleveranciers bieden een testfunctie. Daarmee kun je controleren of het ontvangende systeem de webhook correct ontvangt voordat je de koppeling live zet.

Wat zijn de voordelen van webhooks?

Een belangrijk voordeel is dat informatie snel kan worden doorgestuurd zodra er iets gebeurt. Het ontvangende systeem hoeft daardoor niet voortdurend zelf naar wijzigingen te zoeken.

Dat kan het aantal onnodige API-verzoeken verminderen. Daarnaast kunnen processen sneller reageren op bijvoorbeeld betalingen, bestellingen of nieuwe leads.

Webhooks zijn vooral nuttig voor:

• realtime of snelle meldingen;
• automatische workflows;
• minder polling;
• systemen direct laten reageren;
• gebeurtenissen tussen applicaties doorgeven.

Of een webhook de beste oplossing is, hangt af van het proces. Soms is een gewone API-request praktischer en in andere situaties worden API’s en webhooks gecombineerd.

Wanneer gebruik je een webhook?

Een webhook is vooral geschikt wanneer systeem B iets moet doen zodra er in systeem A een bepaalde gebeurtenis plaatsvindt. Denk aan een succesvolle betaling, nieuwe bestelling of ingevuld formulier.

Moet een applicatie juist op een zelfgekozen moment informatie kunnen opvragen? Dan ligt het gebruik van een API meer voor de hand.

In de praktijk hoef je daarom niet altijd te kiezen tussen API of webhook. Moderne softwarekoppelingen gebruiken vaak beide technieken om gegevens efficiënt tussen systemen te laten bewegen.

Automatisch reageren op gebeurtenissen

Het belangrijkste verschil om te onthouden is dat een webhook informatie naar een ander systeem pusht wanneer een gebeurtenis plaatsvindt. Het ontvangende systeem hoeft daardoor niet voortdurend te controleren of er nieuwe informatie beschikbaar is.

Webhooks zijn daarom een belangrijk onderdeel van veel geautomatiseerde processen. Samen met API’s maken ze het mogelijk dat verschillende applicaties vrijwel direct op elkaar reageren en gegevens uitwisselen.