Webhooks of periodiek ophalen: kies op snelheid én herstelbaarheid

Vertaal realtime naar een zakelijke eis

Realtime klinkt aantrekkelijk, maar benoemt nog geen bruikbaar criterium. Een bijgewerkt klantadres kan mogelijk binnen een uur beschikbaar zijn; een capaciteitsscherm voor de planning kan kortere vertraging nodig hebben. Vraag welke beslissing wordt genomen en wat er gebeurt wanneer de gegevens ouder zijn. Beschrijf het acceptabele tijdvenster en de reactie wanneer dat wordt overschreden.

Gebruik voor een fictieve proef een orderoverzicht dat iedere werkdag wordt gecontroleerd. Bij zo’n proces kan overzichtelijke periodieke verwerking geschikter zijn dan een complexe continue stroom. Voor een andere toepassing, zoals een medewerker direct wijzen op een nieuwe hulpaanvraag, kan een gebeurtenisbericht waardevol zijn. De zakelijke behoefte bepaalt de aanpak; een technische voorkeur is geen vervanging voor die afweging.

Onderzoek welke gebeurtenissen beschikbaar zijn

Een product kan webhooks aanbieden voor een nieuw contact maar niet voor wijzigingen aan relevante subvelden. Een melding kan slechts een verwijzing bevatten, waarna je de actuele staat afzonderlijk moet ophalen. Controleer per gebeurtenis welke inhoud wordt geleverd, welke voorwaarden gelden en of verwijderingen of statusovergangen ook herkenbaar zijn. Vraag bij twijfel een werkend voorbeeld in de juiste administratie.

Leg vast of je de toestand op het moment van de gebeurtenis nodig hebt of de actuele toestand op het moment van verwerking. Dat verschil beïnvloedt het resultaat wanneer meerdere wijzigingen snel volgen. Een melding met een verwijzing is niet vanzelf een volledig historisch bewijs. Als de bron geen vereiste informatie bewaart, moet de scope worden aangepast of een andere vastlegging worden onderzocht.

Ontvang meldingen zonder langdurig te blokkeren

Een webhookontvanger moet de levering volgens het leverancierscontract kunnen beantwoorden. Langdurige zakelijke verwerking in hetzelfde verzoek kan leiden tot een fout of herhaalde levering. GitHub adviseert bijvoorbeeld snelle beantwoording en beschrijft asynchrone verwerking; de concrete tijdsgrens is leveranciersspecifiek. Een ontwerp kan ontvangst eerst vastleggen en de inhoud daarna gecontroleerd verwerken.

Bevestig ontvangst niet alsof daarmee de zakelijke opdracht voltooid is. Maak zichtbaar welke berichten zijn ontvangen, welke nog wachten en welke daadwerkelijk tot een doelresultaat hebben geleid. Test een onderbreking na ontvangst maar vóór uitvoering. Het bericht moet dan terugvindbaar blijven. Alleen een snelle succesresponse zonder duurzame vastlegging kan een melding laten verdwijnen terwijl de bron denkt dat de levering goed is gegaan.

Welke ontvangstmethode je ook kiest, ontbrekende of mislukte verwerking moet terug te vinden zijn: Een API-koppeling werkt niet meer: onderzoek en herstel zonder dubbel werk.

GitHub: Best practices for using webhooks ↗

Controleer authenticiteit en inhoud

Een publiek webhookadres kan onbedoelde of vervalste verzoeken ontvangen. Gebruik de door de leverancier aangeboden authenticiteitscontrole en valideer de relevante inhoud voordat verwerking begint. GitHub documenteert onder meer het gebruik van een webhookgeheim en HTTPS. Dat zijn concrete bronaanwijzingen; een passend ontwerp moet daarnaast rekening houden met de werkelijk gekozen leverancier en de eigen infrastructuur.

Een geldig bericht kan nog steeds een ongewenst type bevatten of naar de verkeerde administratie verwijzen. Controleer daarom gebeurtenistype, beoogde omgeving en de zakelijke grens. Laat testberichten geen productiehandelingen starten. Bewaar geen toegangssleutels in de URL en neem geheimen niet op in foutmeldingen. Geef operators voldoende referenties voor onderzoek zonder het hele bericht onbeperkt in brede meldingskanalen te verspreiden.

GitHub: Best practices for using webhooks ↗

Ontwerp periodiek ophalen zorgvuldig

Bij polling bepaal je een selectie zoals gewijzigd sinds het laatst bevestigde punt. Onderzoek hoe de API sorteert, pagineert en omgaat met gelijke tijdstempels. Een wijziging tijdens het ophalen kan anders buiten een onzorgvuldig gekozen venster vallen. Bewaar het verwerkingspunt pas wanneer de bijbehorende selectie voldoende is afgehandeld en een herstart de resterende items kan terugvinden.

Test meerdere pagina’s en veranderingen op de grens. Werk bijvoorbeeld met een gecontroleerde overlap als de API daarvoor geschikt is, en herken herhaalde items met dezelfde verwerkingsregels als elders. Een brede overlap zonder bescherming kan dubbel werk veroorzaken; helemaal geen overlap kan gemiste wijzigingen verbergen. Documenteer de keuze en de feitelijke API-eigenschappen waarop die keuze steunt, in plaats van één universele intervalinstelling te beloven.

Gebruik beide paden met dezelfde zakelijke bescherming

Een webhook kan een wijziging snel signaleren, terwijl een periodieke aansluiting later controleert of alle relevante records verwerkt zijn. Dat kan herstel verbeteren. Beide routes moeten dan wel dezelfde identiteit en dezelfde beslissing over reeds uitgevoerde handelingen gebruiken. Twee losse scripts die ieder alles aanmaken kunnen juist meer duplicaten veroorzaken dan één eenvoudige route.

Maak een fictieve proef waarin een webhook bewust niet wordt bezorgd. De aansluiting ontdekt de ontbrekende order en verwerkt die volgens dezelfde regels. Laat daarna de vertraagde webhook alsnog arriveren. Er mag geen tweede concept ontstaan. Het verwachte resultaat is één herkenbare zakelijke verwerking, met zichtbare informatie dat het tweede pad dezelfde gebeurtenis of opdracht opnieuw heeft aangetroffen.

Stuur op zakelijke achterstand

Meet niet alleen hoeveel webhooks binnenkomen of wanneer de laatste poll draaide. Een succesvolle poll kan nul resultaten tonen omdat de selectie verkeerd is; een actieve webhook kan slechts een deel van de gebeurtenissen ontvangen. Combineer technische signalen met een controle op de relevante bron- en doelreferenties. Kies een controle die past bij de gegevens en het proces.

Laat het overzicht tonen welke periode betrouwbaar is gecontroleerd en hoeveel werk nog openstaat. Bepaal wie reageert wanneer dat venster achterloopt. Kan het bedrijf tijdelijk handmatig verder, en hoe voorkom je dat later dezelfde handeling opnieuw automatisch wordt uitgevoerd? Een noodwerkwijze moet in het herstelplan staan. Anders wordt een korte leveranciersstoring na herstel alsnog een bron van dubbele of tegenstrijdige acties.

Kies op bewezen mogelijkheden

Vergelijk webhooks en polling met dezelfde scenario’s: normale wijziging, hoge activiteit, dubbele bezorging, tijdelijke uitval, verlopen toegang en een gemiste gebeurtenis. Kijk naar vertraging, begrijpelijkheid van fouten en de hoeveelheid handmatig onderzoek. Een oplossing die op papier direct werkt kan operationeel lastiger zijn dan een eenvoudigere batch met een heldere dagelijkse controle.

Schrijf de uiteindelijke keuze als een afspraak: deze gebeurtenissen starten verwerking, dit is de gewenste actualiteit, zo worden achterstanden ontdekt en zo wordt herstel uitgevoerd. Voeg de API-afhankelijkheden toe. Herzie de keuze wanneer het proces of de leverancier verandert. Je hoeft niet elk systeem dezelfde techniek op te leggen om één samenhangende, uitlegbare en controleerbare integratie te maken.

Van uitleg naar een concrete projectkeuze

Leg je aannames, open vragen en oplevercriteria vast in de bijbehorende tool. Gebruik de dienstengidsen om uitvoering en afbakening te bespreken.

• API-koppeling laten maken ↗
• CRM Integratie ↗

Vragen over dit onderwerp

Verder met een aansluitende vraag