Webhooks en periodieke API-verzoeken bieden elk een andere manier om gegevens tussen systemen uit te wisselen. Lees hoe de keuze doorwerkt in snelheid, serverbelasting en de afhandeling van fouten, dubbele berichten en gemiste updates.
Hoe webhooks en periodiek pollen gegevens uitwisselen
Pollen? Daarmee vraagt je systeem op gezette tijden aan een API of er nieuwe data klaar staat. Stel je hebt een app die elke minuut kijkt of een orderstatus is aangepast. Het is dus altijd het vragende systeem dat begint. De API geeft terug: vers nieuws, een lege lijst of een signaal dat even wachten prima is.
Webhooks draaien dat plaatje om. Nu stuurt het bronsysteem een HTTP-verzoek zodra er iets gebeurt. Dat verzoek? Meestal een type event, een uniek ID (voor dubbele controle) en details over de wijziging, zoals bij een klantupgrade of betaalstatus. Jij ontvangt het verzoek, antwoordt met een statuscode terug. Succes betekent hier: "ontvangen", niet per se "helemaal verwerkt".
Het verschil vraagt iets van je ontwerp. Voor pollen heb je een geplande taak nodig, je moet checken wat sinds de vorige keer veranderd is en afspreken hoe vaak je kijkt. Met webhooks moet je applciatie publiek bereikbaar zijn, de afzender controleren en inkomende verzoeken goed afhandelen. Maar in de praktijk: je API blijft het kanaal, alleen bepaalt de andere kant nu het moment. Voor AI-automatisering kan een webhook zo’n integratie activeren.
Wanneer periodiek pollen past bij de integratie
Gebruik pollen als een systeem geen webhooks kan sturen, jouw infrastructuur geen inkomende verbindingen accepteert, of als directe verwerking niet nodig is. Handig bij interne tools achter een firewall. Uitgaand verkeer mag soms wel, een openbaar endpoint vaak niet. Dan past een tijdgestuurde check bij de grenzen van je omgeving.
Tussenpozen zijn bepalend voor actualiteit. Hoe korter je interval, hoe sneller een mutatie opvalt. Nadeel: veel lege checks, druk op de API. Met langere tussenpozen bespaar je verkeer, maar zijn gebruikers langer niet bij. Rate limits en quota zetten de praktijk naar je hand: te snel? Dan krijg je fouten, of raakt je quota op waardoor andere taken stilvallen.
De beste poller haalt alleen verschillen op sinds het laatst bekende punt: bijvoorbeeld via een cursor of tijdstempel. Lukt dat niet, dan zal elke run de hele bulk ophalen en vergelijken, wat veel kost. Die cursor moet je strak beheren: opslaan vóór alles verwerkt is, kan updates missen als daarna iets misgaat. Te laat opslaan, en je verwerkt dubbel bij een crash. Het is dus geen simpele timer, maar een kloppende cyclus van ophalen, verwerken en voortgang boeken.
Wanneer webhooks sneller en doelmatiger zijn
Zie je graag updates direct na iedere wijziging? Of draait de bron soepel in het versturen van meldingen? Dan zijn webhooks je vriend. Denk aan nieuwe supporttickets, abonnementswijzigingen of een betalingsbevestiging: de ontvangende app hoeft niet de hele tijd te polsen en krijgt een seintje zodra het relevant is. Dat scheelt lege verzoeken én laat je direct actie ondernemen.
Maar, de ontvanger krijgt er werk bij. Je endpoint moet alle inkomende pieken aankunnen, zorgvuldig de afzender nagaan en binnen de tijd reageren. Doe je te lang over je eerste antwoord? Dan denkt het bronsysteem misschien dat je niet luistert en stuurt het hetzelfde bericht later nog eens. Een veilige tactiek: sla eerst het bericht op in een queue (of inbox), geef dan pas groen licht terug. Je verwerking mag daarna op de achtergrond uitlopen zonder de bron te laten wachten. Ook AI-agents kunnen op zulke events reageren.
Let op de dienstverlener: niet alles krijgt een eigen webhook. Soms komt alleen een verwijzing binnen, en moet je alsnog data ophalen. Events kunnen ook door elkaar binnenkomen. Webhooks lossen synchronisatievragen niet op, ze maken alleen zichtbaar waar ze zich voordoen.
Serverbelasting, schaalbaarheid en API-limieten vergelijken
Pollen kan een flinke belasting opleveren, vooral bij veel gebruikers of regelmatige checks. Heb je duizend accounts die elk om de minuut checken? Dat tikt aan, zelfs als er weinig verandert. Het wordt snel erger wanneer je steeds alle data ophaalt of wanneer meerdere pollers gelijktijdig draaien. Dit kun je verlichten met centrale planning en door incrementeel te werken.
Webhooks zijn zuiniger met verzoeken als veranderingen zeldzaam zijn. De pieken komen bij bulkacties: een massale import? Dan kan je endpoint overspoeld raken. Zonder buffer gaat er dan snel iets mis. Zet een queue tussen je endpoint en verwerking, dan kun je de snelheid uitlijnen. Houd in de gaten: groeit je queue sneller dan je afhandelt?
Kijk niet alleen naar het aantal HTTP-calls. Webhooks vragen vaak alsnog een extra API-verzoek om details. Pollen kan juist meerdere wijzigingen in een keer afleveren. Factoren zoals retries, paginering, de grootte van de berichten en limieten hebben invloed. Kijk naar de tijd tussen wijziging en verwerking, hoeveel fouten optreden en of er achterstanden ontstaan. Die cijfers laten je zien of je aanpak ook bij een piek blijft werken.
Retries en tijdelijke fouten beheersbaar maken
Verbinding kwijt? Tijdelijk een foutmelding? Of je proces valt weg, allemaal reden om opnieuw te proberen. Bij webhooks zorgt meestal het bronsysteem voor retries. Na een timeout of bij een fout stuurt die op zijn manier het bericht opnieuw. Dat gebeurt volgens schema's van de leverancier; na een half uur geen resultaat kan het bericht verdwijnen.
Bij pollen ben je zelf aan zet. Na een fout probeer je een run opnieuw, maar corrigeer met back-off en variatie wanneer je dat doet. Onbeperkt snel herhalen is zinloos als de bron zelf overbelast is. Gebruik de Retry-After-header als die gestuurd wordt. Permanente fouten, zoals slechte authenticatie, moet je niet blijven proberen. Geef direct een signaal af om in te grijpen.
Bepaal altijd wat een echt geslaagde stap is. Geef niet zomaar een 200 terug voor een webhook, maar pas wanneer het bericht echt goed opgeslagen is. Voor pollen geldt hetzelfde: cursor pas bijwerken na de volledige, geldige verwerking. Houd altijd vast: ID van het event, wat voor fout, het volgende geplande moment van actie. Zo houd je onderscheid tussen incidentele verstoringen en structureel achterlopen.
Dubbele webhookberichten idempotent verwerken
Het komt voor dat je hetzelfde webhookbericht meer dan eens ontvangt. Na een timeout, bij netwerkhaperingen of omdat je bevestiging verloren gaat. Ook een poller kan door een mislukte opslag meermaals hetzelfde record bewerken. Dubbele afhandeling hoort er dus gewoon bij.
Krijg je een event-ID van de bron? Gebruik deze als idempotentiesleutel en leg ze uniek vast, bijvoorbeeld met een unieke index op je inbox. Ontvang je hetzelfde verzoek later nog eens, dan sla je die gewoon over. Soms moet je een combinatie van object-ID en soort gebeurtenis gebruiken als er geen uniek event-ID is. Hashen van een payload geeft alleen garantie als dat veld geen onbelangrijke veranderingen bevat.
Controleren op doublures geldt ook voor externe acties. Je wilt geen dubbele facturen versturen of twee keer dezelfde notificatie mailen. Gebruik transacties of het outboxpattern om te zorgen dat alles veilig verwerkt wordt voordat je de status op verwerkt zet. Unieke sleutels voorkomen dat parallelle processen onopgemerkt hetzelfde bericht behandelen. De precieze uitwerking hangt af van wat er kapot kan gaan als er dubbel gewerkt wordt.
Gemiste updates opsporen en herstellen
Webhooks geven geen garantie op een compleet event-overzicht. Als je endpoint offline is, een bewaartermijn verloopt of een eventtype niet aangevinkt staat, kunnen berichten verdwijnen. Bij pollers kun je wijzigingen missen als je cursor niet actueel wordt opgeslagen, een tijdstempel niet uniek genoeg is of je niet alle pagina's meeneemt in je run.
Maak je integratie veerkrachtig door regelmatig je data met de bron te vergelijken. Haal bijvoorbeeld alles op uit een ruim tijdvenster en herverwerk die records; dubbele verwerking vang je op met een idempotente aanpak. Voor grote datasets kun je de check opdelen in kleinere stukken, bijvoorbeeld per week of per status.
Leg voldoende vast: het laatste cursorpunt, de eerste niet-verwerkte melding, tellingen van fouten en wanneer de laatste volledige sync is afgerond. Door te monitoren op groeiende wachtrijen of stagnerende polling-cursors zie je waar het misgaat. Zorg voor een herstelroute waarmee je (bijvoorbeeld) specifieke periodes of objecten kunt synchroniseren, zonder alles overnieuw te doen. Zo blijft een klein incident beperkt. Voor voorraad tussen systemen zie webshop voorraad koppelen.
Volgorde, verouderde gegevens en gebeurtenisversies
Events komen niet altijd in de volgorde waarin ze zijn gebeurd aan. Soms heeft een webhook vertraging of lopen processen parallel, zodat je in je applicatie een oudere status overschrijft. Vooral belangrijk bij statusinfo, voorraadden of data waarin volgorde telt.
Maak gebruik van een oplopend versienummer, sequence ID of tijdstempel als de bron dat biedt. Zie je een lagere versie binnenkomen, dan kun je die negeren of apart opslaan. Op tijd vertrouwen kan misleidend zijn als klokken niet gesynchroniseerd zijn. In onvoorspelbare situaties, zoals complexe statuswissels, is het veiliger om het actuele object uit de bron te halen na ontvangst van een twijfelachtig event.
Kijk altijd naar de betekenis van een payload: wordt een verandering beschreven, of alleen dat iets is gewijzigd? In het laatste geval moet je alsnog je info ophalen. Webhooks en pollen samen inzetten werkt prima: webhooks activeren snelle verwerking, periodieke checks vangen verschillen op. De aanpak hangt af van of per object de hele reeks verwerkt moet worden, of alleen het eindresultaat telt.
Beveiliging en observability van API-koppelingen
Een webhookendpoint is een ingang voor publiek verkeer en moet dus de afzender valideren. Werk met ondertekening: stuur een geheime sleutel mee en check die handtekening over de ruwe requestbody, niet na omzetting naar JSON. Gebruik bij voorkeur unieke timestamps of nonces om herhalingsaanvallen te vermijden. Houd sleutels buiten logbestanden en roteer ze volgens vast schema.
Pollen gebruikt tokens of sleutels voor toegang. Die moeten veilig, met overeenkomstige rechten, beheerd worden. Geen sleutels in code of logs stoppen. Oefen terughoudendheid met payloads die gevoelige of bijzondere persoonsgegevens bevatten. Laat je webhookendpoint altijd snel reageren, voer zware logica elders uit zodat een aanval of grote piek niet meteen je hoofdproces vastzet. Een PHP developer kan zo’n endpoint op maat bouwen.
Meting en logging zijn onmisbaar. Leg responstijden, foutcodes, retryaantallen, queue-lengtes en de leeftijd van je oudste onbeantwoorde bericht apart vast. Koppel event-ID's aan logs zodat je het pad van een verzoek kunt herleiden. Geef niet alleen een alarm bij uitval, let ook op stokkende verwerking. Hiermee ontdek je problemen snel, bijvoorbeeld in authenticatie, validatie of limieten bij aangesloten systemen.
Veelgestelde vragen
Hoe beveilig ik een webhook-endpoint tegen vervalste verzoeken?
Beveilig je webhook-endpoint door elk verzoek te verifiëren via cryptografie en alleen via HTTPS te accepteren. Gebruik altijd de handtekeningmethode van je leverancier: alleen daarmee weet je of de payload onderweg niet is aangepast en van wie hij komt.
- Bereken de handtekening over de originele requestbody en vergelijk deze op een veilige manier met wat is meegeleverd.
- Check eventueel meegegeven tijdstempels om oude (mogelijk gestolen) berichten te negeren.
- Sla je geheim buiten je code op en roteer het regelmatig.
- Stop gevoelige data of tokens niet in je logs.
Alleen het IP van de bron controleren of een geheim in de URL zetten is niet afdoende voor echte zekerheid.
Hoe test ik een webhook lokaal voordat ik deze in productie zet?
Test een webhook lokaal door een test-call naar je ontwikkelmachine te sturen en de hele afhandeling na te lopen. Kan de leverancier je computer niet direct bereiken? Gebruik dan een tijdelijke tunnelservice om verkeer om te leiden.
- Werk met testtijdens en aparte geheimen, niet je productie-credentials.
- Simuleer goede, maar ook onjuiste en missende gegevens om je validatie te testen.
- Probeer hetzelfde event-ID meerdere keren voor idempotentiecontrole.
- Kijk hoe je afhandeling omgaat met time-outs en fouten.
Controleer dat er niets vertrouwelijks wordt gelogd en sluit je publieke tunnel zodra je klaar bent met testen.
Wanneer is een combinatie van webhooks en periodiek pollen verstandig?
Je combineert ze als je wilt dat veranderingen snel binnenkomen, maar je ook af en toe wilt checken of alles klopt met de bron. Webhooks geven een seintje voor snelle verwerking, de poller detecteert gemiste events.
- Gebruik het webhookbericht als trigger om direct één object te verwerken.
- Laat daarnaast periodiek een run draaien die recent veranderde of relevante objecten vergelijkt.
- Maak beide verwerkingsflows idempotent, zodat een wijziging niet dubbel telt.
- Vergelijk versies of tijden voordat je overschrijft.
Zo krijg je snelheid én herstelmogelijkheid, zonder iedere keer alle data te hoeven ophalen.
Hoe bepaal ik een geschikt pollinterval voor een API?
Kies het pollinterval op basis van de maximaal acceptabele vertraging voor je gebruikers, de limieten van de API en het aantal verwachte veranderingen. Start vanuit de gewenste reactietijd, kijk dan hoeveel API-verzoeken er uitrollen.
- Reken uit hoeveel totale checks je per uur doet voor al je accounts samen.
- Laat altijd wat ruimte voor onverwachte herhalingen of andere apps die dezelfde API gebruiken.
- Meet hoe vaak controles echt nieuwe data opleveren, en hoe lang gegevens onderweg blijven.
- Pas je frequentie aan als de actualiteit niet volstaat of als veel checks niets opleveren.
Verschillende datasets of objecttypes kun je hun eigen interval geven, zodat weinig veranderende data niet onnodig vaak gechecked wordt.
Hoe voorkom ik dat wijzigingen in een webhook-payload mijn integratie breken?
Maak je webhookafhandeling tolerant voor ontbrekende of onverwachte velden en test schemawijzigingen. Ga niet uit van één vast voorbeeld, leveranciers kunnen het schema uitbreiden of naast elkaar meerdere versies gebruiken.
- Weet welke velden verplicht zijn en vang gevallen van missende of extra velden goed op.
- Negeer onbekende velden waar dat kan, blokkeer niet het hele verzoek erom.
- Voer samentests/procescontroles uit met verschillende versies van events.
- Leg fouten altijd vast met event-ID en eventueel schemaversie, maar zonder gevoelige payloadinformatie.
Geeft je leverancier het versienummer expliciet door, stuur dan je verwerking daarop en bereid eventuele wijzigingen ruim vooraf voor.
Foto: Szabó Viktor