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
Bij periodiek pollen vraagt een systeem op vaste momenten aan een API of er nieuwe gegevens beschikbaar zijn. Een applicatie kan bijvoorbeeld iedere minuut controleren of een bestelling van status is veranderd. Het ontvangende systeem begint die uitwisseling zelf; de API antwoordt met nieuwe gegevens, een lege lijst of een status die aangeeft wanneer opnieuw controleren zinvol is.
Een webhook draait de richting van het initiatief om. Het systeem waarin een gebeurtenis plaatsvindt, stuurt een HTTP-verzoek naar een vooraf opgegeven adres. Dat verzoek bevat bijvoorbeeld een gebeurtenistype, een uniek ID en gegevens over een gewijzigde klant of betaling. De ontvangende applicatie verwerkt het bericht en geeft een HTTP-statuscode terug. Een succesvolle ontvangst betekent doorgaans alleen dat het verzoek is geaccepteerd, niet dat iedere vervolgstap al is afgerond.
Dit verschil bepaalt het ontwerp van de integratie. Pollen vereist een geplande taak, een manier om wijzigingen sinds de vorige controle te herkennen en regels voor de frequentie. Een webhook vereist een publiek bereikbaar endpoint, authenticatie en verwerking van inkomende verzoeken. Beide varianten halen gegevens via een API op of versturen gegevens via een verzoek; het onderscheid zit vooral in wie het moment van communicatie bepaalt.
Wanneer periodiek pollen past bij de integratie
Pollen is bruikbaar wanneer een systeem geen webhooks aanbiedt, wanneer de ontvangende omgeving geen inkomende verbindingen kan aannemen of wanneer wijzigingen niet direct verwerkt hoeven te worden. Een interne applicatie achter een firewall kan bijvoorbeeld wel uitgaand API-verkeer toestaan, maar geen openbaar endpoint beschikbaar stellen. Een geplande controle sluit dan aan op de bestaande netwerkgrenzen en operationele inrichting.
De intervalkeuze beïnvloedt zowel de actualiteit als het aantal verzoeken. Een korte interval beperkt de tijd tussen een wijziging en de ontdekking ervan, maar veroorzaakt ook veel verzoeken zonder nieuwe gegevens. Een lange interval verlaagt het verzoekvolume, terwijl gebruikers langer met verouderde informatie kunnen werken. Rate limits en API-quota maken die afweging concreet: overschrijding kan leiden tot foutantwoorden, tijdelijke blokkades of minder ruimte voor andere processen.
Een goede poller vraagt waar mogelijk alleen wijzigingen op sinds een bekende cursor, tijdstempel of versie. Zonder zo’n mechanisme kan elke controle dezelfde volledige dataset ophalen en vergelijken, wat netwerkverkeer en databasewerk vergroot. De cursor moet zorgvuldig worden bijgehouden: te vroeg opslaan kan updates overslaan als verwerking daarna mislukt; pas opslaan na succesvolle verwerking kan bij een herstart dezelfde records opnieuw opleveren. Pollen is dus geen eenvoudige timer, maar een gecontroleerde cyclus van ophalen, verwerken en voortgang vastleggen.
Wanneer webhooks sneller en doelmatiger zijn
Webhooks zijn geschikt wanneer een wijziging snel beschikbaar moet zijn en het bronsysteem betrouwbare gebeurtenissen kan versturen. Een nieuw supportticket, een gewijzigde abonnementsstatus of een afgeronde transactie kan vrijwel direct een bericht opleveren. De ontvangende applicatie hoeft niet voortdurend te controleren of er iets is veranderd. Daardoor verdwijnen veel lege verzoeken en kan verwerking starten op het moment dat de bron een relevante gebeurtenis kent.
Die efficiëntie verplaatst een deel van de complexiteit naar de ontvangende kant. Het endpoint moet verzoeken kunnen aannemen tijdens pieken, de herkomst van berichten controleren en snel een passend antwoord geven. Als de applicatie binnen de maximale responstijd langdurig bedrijfslogica uitvoert, kan het bronsysteem een timeout zien en het bericht opnieuw versturen. Een robuust patroon is daarom het verzoek eerst veilig op te slaan in een queue of inbox en pas daarna een succesvolle ontvangst te bevestigen. Achtergrondverwerking kan vervolgens onafhankelijk schalen.
Een webhook is bovendien afhankelijk van de mogelijkheden van de leverancier. Niet iedere gebeurtenis heeft een eigen webhook, en sommige systemen sturen alleen een beperkte verwijzing naar het gewijzigde object. De ontvanger moet dan alsnog een API-verzoek doen om de actuele gegevens op te halen. Ook kunnen gebeurtenissen in een andere volgorde aankomen dan waarin ze plaatsvonden. De keuze voor webhooks neemt synchronisatievragen dus niet weg; ze verschuift het moment waarop die vragen zichtbaar worden.
Serverbelasting, schaalbaarheid en API-limieten vergelijken
Bij pollen ontstaat belasting door het aantal controles, de omvang van de antwoorden en de verwerking van herhaalde gegevens. Duizend gekoppelde accounts die elk iedere minuut worden gecontroleerd, kunnen samen een aanzienlijk verzoekvolume opleveren, ook als er weinig verandert. Het patroon wordt zwaarder wanneer iedere controle volledige objecten ophaalt of wanneer meerdere processen onafhankelijk dezelfde API raadplegen. Een centrale planner, gedeelde cursors en incrementele endpoints beperken die verspilling.
Webhooks verminderen doorgaans het aantal verzoeken wanneer gebeurtenissen relatief schaars zijn. De belasting volgt dan eerder het aantal wijzigingen dan een vast tijdschema. Dat maakt pieken belangrijk: een bulkimport kan in korte tijd duizenden meldingen veroorzaken. Zonder buffer kan het endpoint overbelast raken, terwijl een queue de instroom opvangt en verwerking doseert. De ontvangende applicatie moet daarbij bewaken of de wachtrij niet sneller groeit dan zij berichten kan verwerken.
Vergelijk niet alleen het aantal HTTP-verzoeken. Een webhook kan voor ieder bericht nog een API-ophaalverzoek vereisen, terwijl pollen in één antwoord meerdere wijzigingen kan bevatten. Ook tellen retries, paginering, payloadgrootte en quota mee. Meet daarom verzoeken per verwerkte wijziging, de tijd tussen bronwijziging en verwerking, foutpercentages en de omvang van achterstanden. Die gegevens maken zichtbaar of de gekozen aanpak efficiënt blijft bij normale belasting én bij uitzonderlijke pieken.
Retries en tijdelijke fouten beheersbaar maken
Netwerkverbindingen vallen weg, servers geven tijdelijk een fout en processen kunnen tijdens verwerking stoppen. Daarom moet een integratie bepalen wanneer een mislukte communicatie opnieuw wordt geprobeerd. Bij webhooks ligt de retry vaak bij het verzendende systeem. Dat systeem kan bij een timeout of een serverfout hetzelfde bericht later opnieuw aanbieden, soms met oplopende tussenpozen. De precieze regels verschillen per leverancier; berichten kunnen na een beperkte periode uit de retryreeks verdwijnen.
Bij pollen beheert de ontvanger meestal zelf de herhaling. Een taak kan na een tijdelijke fout later opnieuw draaien, maar een onbegrensde snelle retry veroorzaakt extra druk op een API die al problemen heeft. Exponentiële back-off met willekeurige spreiding voorkomt dat veel processen tegelijk opnieuw beginnen. Een expliciete maximumfrequentie en respect voor een Retry-After-header helpen de belasting binnen de grenzen van de API te houden. Permanente fouten, zoals ongeldige authenticatie, vragen om een melding en herstel van de configuratie in plaats van eindeloos opnieuw proberen.
Leg vast welke stap als geslaagd geldt. Een HTTP 200 van een webhookendpoint mag pas worden teruggegeven nadat het bericht duurzaam is opgeslagen; anders kan een procescrash na het antwoord tot gegevensverlies leiden. Bij pollen moet de cursor pas worden bijgewerkt volgens een consistente verwerkingsstrategie. Log voor iedere poging het bericht- of request-ID, de foutcategorie en het volgende geplande moment. Zonder die gegevens zijn tijdelijke incidenten lastig te onderscheiden van een structurele achterstand.
Dubbele webhookberichten idempotent verwerken
Een webhook kan meerdere keren aankomen zonder dat er meerdere gebeurtenissen hebben plaatsgevonden. Het verzendende systeem weet na een timeout mogelijk niet of de ontvanger het bericht al heeft verwerkt. Het probeert opnieuw, ook wanneer het eerste verzoek wel is aangekomen maar de bevestiging onderweg verloren ging. Ook pollers kunnen records opnieuw ophalen als een proces uitvalt voordat de voortgang is opgeslagen. Dubbele verwerking is daarom een normaal scenario in gedistribueerde gegevensuitwisseling.
Gebruik waar mogelijk een stabiel event-ID als idempotentiesleutel. Sla dat ID op in een inbox- of verwerkingstabel met een unieke databaseconstraint. Bij een herhaald verzoek ziet de applicatie dat het event al geregistreerd is en voorkomt zij dat dezelfde bedrijfsactie opnieuw wordt uitgevoerd. Als de bron geen event-ID levert, kan een combinatie van object-ID, gebeurtenistype en versienummer bruikbaar zijn. Een hash van de volledige payload is minder betrouwbaar wanneer niet-relevante velden of serialisatievolgorde kunnen verschillen.
Idempotentie moet ook gelden voor gevolgen buiten de database. Een dubbele verwerking mag bijvoorbeeld niet twee facturen aanmaken of twee externe notificaties versturen. Dat vraagt om een transactie, een outboxpatroon of een eigen idempotentiesleutel bij het volgende systeem. Markeer een bericht niet als verwerkt voordat de noodzakelijke wijzigingen duurzaam zijn vastgelegd. Tegelijk voorkomt een unieke sleutel dat parallelle workers hetzelfde bericht ongemerkt tegelijk uitvoeren. De precieze grens hangt af van welke effecten herhaling heeft in het bedrijfsproces.
Gemiste updates opsporen en herstellen
Webhooks leveren niet automatisch een volledig en blijvend overzicht van alle wijzigingen. Een endpoint kan tijdelijk onbereikbaar zijn, een leverancier kan een event niet meer opnieuw aanbieden na het verlopen van zijn bewaartermijn, of een configuratiefout kan een gebeurtenistype uitsluiten. Pollen kent andere risico’s: een cursor die verkeerd wordt bijgewerkt, een tijdstempelgrens met gelijke waarden of een pagina die niet volledig is opgehaald, kan records buiten de volgende controle laten vallen.
Ontwerp daarom een manier om de lokale toestand met de bron te vergelijken. Een periodieke reconciliatie kan bijvoorbeeld gewijzigde objecten sinds een ruime overlapperiode ophalen en opnieuw verwerken. De overlap vangt vertragingen en gelijke tijdstempels op; idempotente verwerking voorkomt dat reeds verwerkte records schadelijk dubbel worden toegepast. Bij grote datasets kan reconciliatie per objectgroep, datumvenster of status worden uitgevoerd om limieten en lange transacties te vermijden.
Bewaar voldoende informatie om een gat te herkennen: laatste succesvolle cursor, oudste onverwerkte gebeurtenis, aantal mislukte verzoeken en tijdstip van de laatste volledige synchronisatie. Een webhookwachtrij die blijft groeien of een poller die geen voortgang maakt, hoort zichtbaar te zijn in monitoring. Maak herstel expliciet: een operator moet een periode opnieuw kunnen ophalen of een object opnieuw kunnen synchroniseren zonder de hele integratie te resetten. Een herstelpad voorkomt dat een klein incident uitmondt in langdurige verschillen tussen systemen.
Volgorde, verouderde gegevens en gebeurtenisversies
De volgorde waarin berichten aankomen is niet altijd de volgorde waarin wijzigingen zijn ontstaan. Een oudere webhook kan vertraagd zijn en na een nieuwere gebeurtenis binnenkomen. Bij parallelle verwerking kan hetzelfde gebeuren nadat berichten wel in de juiste volgorde zijn ontvangen. Als iedere payload blind de lokale waarde overschrijft, kan de applicatie daardoor teruggaan naar een verouderde status. Dit risico is relevant voor statussen, voorraadstanden en andere gegevens waarbij volgorde betekenis heeft.
Gebruik waar de bron die aanbiedt een oplopend versienummer, sequence number of gewijzigde tijdstempel om te bepalen of een update nieuwer is dan de opgeslagen toestand. Een gebeurtenis met een lagere versie kan dan worden genegeerd of alleen worden vastgelegd voor audit. Tijdstempels zijn minder sterk wanneer klokken niet synchroon lopen of de bron beperkte precisie gebruikt. Bij complexe statusovergangen kan het veiliger zijn om na ontvangst het actuele object bij de bron op te halen, in plaats van een losse gebeurtenis als volledige waarheid te behandelen.
Let ook op de betekenis van een eventpayload. Sommige berichten beschrijven een verandering, zoals een veld dat van waarde A naar B ging; andere melden alleen dat een object gewijzigd is. In het tweede geval moet de ontvanger de actuele toestand ophalen. Een combinatie van webhook en periodieke reconciliatie kan dan effectief zijn: gebeurtenissen activeren snelle verwerking, terwijl controles achterstanden en afwijkingen herstellen. De integratie moet per object bepalen of gebeurtenissen opeenvolgend moeten worden verwerkt of dat alleen de nieuwste toestand relevant is.
Beveiliging en observability van API-koppelingen
Een webhookendpoint staat doorgaans open voor inkomende verzoeken en moet daarom de afzender kunnen verifiëren. Een ondertekende payload met een geheime sleutel of een andere vorm van berichtauthenticatie helpt vervalste verzoeken te herkennen. Controleer de handtekening over de exacte ruwe requestbody voordat JSON wordt aangepast of opnieuw geserialiseerd. Vergelijk daarnaast timestamps of noncewaarden om herhaling van onderschepte verzoeken te beperken. Geheimen moeten roteerbaar zijn en niet in applicatielogs terechtkomen.
Ook pollen vereist beveiliging: API-sleutels of OAuth-tokens geven toegang tot gegevens en moeten met passende rechten worden uitgegeven, veilig opgeslagen en tijdig vernieuwd. Beperk toegang tot de benodigde endpoints en gegevens. Log geen volledige payloads wanneer die persoonsgegevens, betaalgegevens of andere gevoelige informatie bevatten. Voor webhooks is het bovendien verstandig het endpoint snel te laten antwoorden en bedrijfslogica buiten het publieke verzoekpad uit te voeren. Dat verkleint de kans dat een aanvaller of een grote berichtenpiek dure processen rechtstreeks activeert.
Observability maakt zichtbaar wat de techniek daadwerkelijk doet. Meet responstijden, foutcodes, retryaantallen, queuehoogte, ouderdom van het oudste bericht en de vertraging tussen bronwijziging en lokale verwerking. Koppel logs aan event-ID’s en request-ID’s, zodat één wijziging door meerdere services te volgen is. Stel waarschuwingen in op afwijkingen, niet alleen op volledige uitval: een poller kan technisch actief zijn terwijl de cursor niet opschuift. Met die signalen zijn fouten in authenticatie, payloadvalidatie, rate limiting en downstreamverwerking afzonderlijk te lokaliseren.
Veelgestelde vragen
Hoe beveilig ik een webhook-endpoint tegen vervalste verzoeken?
Beveilig een webhook-endpoint door de herkomst van elk verzoek cryptografisch te controleren en alleen via HTTPS te communiceren. Gebruik bij voorkeur de handtekeningmethode van de leverancier: die controleert of de payload onderweg niet is aangepast en door een partij met het juiste geheim is verstuurd.
- Bereken de handtekening over de ongewijzigde requestbody en vergelijk die veilig met de meegestuurde handtekening.
- Controleer, als de leverancier dit ondersteunt, een tijdstempel om oude verzoeken te weigeren.
- Bewaar geheimen buiten de broncode en roteer ze volgens een vast proces.
- Log geen tokens of gevoelige payloadgegevens.
Een gedeeld geheim in een URL of een controle op alleen het IP-adres is op zichzelf geen sterke verificatie.
Hoe test ik een webhook lokaal voordat ik deze in productie zet?
Test een webhook lokaal door een testverzoek naar je ontwikkelomgeving te sturen en te controleren of je applicatie het veilig ontvangt, valideert en verwerkt. Als de leverancier geen lokaal endpoint kan bereiken, kun je voor ontwikkeling een beveiligde tunneldienst gebruiken om verkeer tijdelijk naar je computer door te sturen.
- Gebruik testgegevens en geheimen die niet voor productie bedoeld zijn.
- Test geldige verzoeken, ongeldige handtekeningen en ontbrekende velden.
- Stuur hetzelfde event-ID meerdere keren om dubbele verwerking te controleren.
- Simuleer time-outs en serverfouten en controleer het gedrag van retries.
Test ook dat gevoelige gegevens niet onbedoeld in logs terechtkomen en verwijder de tijdelijke publieke URL zodra je klaar bent.
Wanneer is een combinatie van webhooks en periodiek pollen verstandig?
Een combinatie is verstandig wanneer je snelle updates wilt ontvangen, maar ook wilt kunnen controleren of je lokale gegevens nog overeenkomen met de bron. Webhooks kunnen wijzigingen direct doorgeven, terwijl een periodieke controle ontbrekende gebeurtenissen kan opsporen of de actuele toestand opnieuw kan ophalen.
- Gebruik webhookberichten als aanleiding om een object direct te verwerken.
- Voer daarnaast op een passend interval een beperkte controle uit, bijvoorbeeld op recent gewijzigde objecten.
- Maak beide verwerkingsroutes idempotent, zodat dezelfde wijziging niet tweemaal effect heeft.
- Vergelijk versies of gewijzigde tijdstippen voordat je lokale gegevens bijwerkt.
Zo combineer je snelle verwerking met een herstelmechanisme, zonder dat de controle onnodig vaak volledige datasets ophaalt.
Hoe bepaal ik een geschikt pollinterval voor een API?
Bepaal het pollinterval op basis van hoe snel wijzigingen beschikbaar moeten zijn, hoeveel verzoeken de API toestaat en hoeveel wijzigingen er gemiddeld plaatsvinden. Begin met de maximale vertraging die voor gebruikers aanvaardbaar is en controleer vervolgens of het verwachte verzoekvolume binnen de quota past.
- Bereken hoeveel controles alle gekoppelde accounts samen per uur veroorzaken.
- Reserveer ruimte voor pieken, retries en andere applicaties die dezelfde API gebruiken.
- Meet hoe vaak een controle nieuwe gegevens oplevert en hoe oud gegevens gemiddeld zijn bij verwerking.
- Pas de frequentie aan als de actualiteit tekortschiet of veel controles leeg blijven.
Gebruik waar mogelijk verschillende intervallen per dataset of prioriteit. Zo hoeven zelden gewijzigde gegevens niet even vaak te worden gecontroleerd als tijdkritische gegevens.
Hoe voorkom ik dat wijzigingen in een webhook-payload mijn integratie breken?
Voorkom brekende fouten door je webhookverwerker tolerant te maken voor velden die ontbreken of nieuw zijn, en door wijzigingen in het payloadschema gecontroleerd te testen. Vertrouw niet op één vaste voorbeeldpayload: leveranciers kunnen gebeurtenissen uitbreiden of verschillende versies naast elkaar aanbieden.
- Controleer welke velden noodzakelijk zijn en behandel optionele velden veilig.
- Negeer onbekende velden waar dat kan, in plaats van het hele bericht af te wijzen.
- Gebruik schema- of contracttests met voorbeelden van iedere ondersteunde gebeurtenisversie.
- Leg fouten vast met event-ID en schemaversie, maar zonder onnodige gevoelige inhoud.
Als de leverancier versies expliciet vermeldt, routeer berichten dan op basis daarvan en plan wijzigingen voordat een oude versie niet meer wordt ondersteund.
