Skip to main content
HomeBlogGidsenHoe gemiste Webhook-updates te verzoenen met periodiek pollen van de API: een handleiding voor hybride synchronisatie

Hoe gemiste Webhook-updates te verzoenen met periodiek pollen van de API: een handleiding voor hybride synchronisatie

17TRACK

Gebruik webhooks voor snelle updates en periodieke API-polling om te controleren of je lokale verzendregistratie nog overeenkomt met de registratie van de provider. Het betrouwbare patroon is om webhook-leveringen duurzaam op te slaan, te vergelijken met de API met behulp van stabiele verzend-ID's en beide paden via dezelfde idempotente updatelogica te verwerken. Polling kan gemiste statuswijzigingen herstellen, maar kan tussentijdse gebeurtenissen niet reconstrueren tenzij de API daadwerkelijk gebeurtenisgeschiedenis beschikbaar stelt.

Gemiste webhookupdates herstellen met periodieke API-polling

Dit draaiboek is bedoeld voor engineers en operationele teams die verantwoordelijk zijn voor het synchroon houden van een orderbeheersysteem, trackingpagina of klantenserviceweergave met verzendgegevens. De centrale regel is eenvoudig: beschouw een webhook als een signaal om een wijziging te inspecteren en te verwerken, niet als bewijs dat elke eerdere wijziging is aangekomen.

Bepaal wat “synchroon” betekent voordat je een interval kiest

Een verzendintegratie moet mogelijk twee verschillende zaken behouden: de huidige status, zoals “onderweg” of “bezorgd”, en de gebeurtenisgeschiedenis die uitlegt hoe die status is bereikt. Een zendingopzoeking van een provider kan de laatste status, een lijst met trackinggebeurtenissen of beide retourneren. Deze API-vormen leiden tot verschillende garanties voor herstel.

Als de opzoeking alleen een momentopname van de huidige status retourneert, kan een reconciliatiepoll je lokale status corrigeren na een gemiste webhook. De poll kan niet bewijzen welke tussentijdse statussen zijn opgetreden. Als de API historische gebeurtenissen met stabiele identificatoren of tijdstempels retourneert, kan de poll mogelijk ook ontbrekende tijdlijnitems herstellen. Controleer het daadwerkelijke responseschema van de provider voordat je downstreamgebruikers een van beide resultaten belooft.

Noteer de velden die je applicatie moet reconciliëren: verzend-ID, vervoerder of tracking-ID, genormaliseerde status, providerstatus, gebeurtenistijd, tijdstip van de laatste providerupdate, bezorggegevens en alle velden die worden gebruikt om klantberichten te activeren. Scheid velden die bij de provider leidend zijn van velden die lokaal worden beheerd, zoals een interne notitie bij een dossier. Een reconciliatietaak mag lokale gegevens niet overschrijven alleen omdat ze ontbreken in een API-response.

Bouw één verwerkingspad voor webhook- en pollresultaten

Webhookhandlers en pollworkers mogen geen concurrerende regels voor statuswijzigingen implementeren. Beide moeten een genormaliseerde waarneming produceren en deze doorgeven aan één reconciliatiefunctie. Die functie valideert de identiteit, vergelijkt de waarneming met de opgeslagen zending, schrijft een veilige update en registreert waarom de wijziging is aangebracht.

  1. Ontvangen en authenticeren. Valideer een webhook met behulp van het gedocumenteerde mechanisme van de provider. Wijs verzoeken af die de validatie niet doorstaan, maar bewaar voldoende niet-gevoelige diagnostische informatie om leveringsproblemen te onderzoeken.
  2. Opslaan vóór bevestiging. Plaats een geldige levering in duurzame opslag of een wachtrij voordat je succes retourneert. Een succesvolle HTTP-response die vóór het opslaan wordt verzonden, creëert een hiaat dat een nieuwe poging van de provider mogelijk niet kan herstellen.
  3. Normaliseren. Breng de payload van de provider of de API-response onder in een gemeenschappelijke interne structuur en behoud de oorspronkelijke waarden van de provider voor onderzoek.
  4. Reconciliëren. Gebruik een stabiele verzendsleutel en een idempotentieregel om dubbele tijdlijnitems, herhaalde meldingen en onnodige schrijfbewerkingen te voorkomen.
  5. Het resultaat auditen. Registreer of de waarneming de zending heeft gewijzigd, al bekend was, ouder was dan de opgeslagen status of handmatige beoordeling vereist.

Een gebeurtenis-ID van de provider is nuttig voor deduplicatie als die bestaat en stabiel is. Als die ontbreekt, kan een samengestelde sleutel nodig zijn, maar de onderdelen ervan moeten passen bij het gegevensmodel van de provider. Twee legitieme scans kunnen dezelfde status en tijdstempel hebben; een sleutel die alleen op die velden is gebaseerd, kan daardoor een echte gebeurtenis weggooien. Bewaar de onbewerkte payload of een verwijzing ernaar gedurende een vastgestelde bewaartermijn, zodat onduidelijke overeenkomsten kunnen worden onderzocht.

Ontwerp de pollinglus rond risico, niet rond één globale timer

Elke bekende zending met dezelfde frequentie pollen verspilt verzoeken en kan de API-limieten onder druk zetten. Houd een set zendingen bij die in aanmerking komen voor reconciliatie en selecteer deze op basis van operationeel risico. Een pas geregistreerde zending die nog geen eerste update heeft ontvangen, een zending met een recente fout bij de verwerking van een webhook en een zending waarvan de status binnen de verwachte workflow niet is gewijzigd, kunnen verschillende schema's vereisen. Een voltooide zending heeft mogelijk slechts één beperkte eindcontrole nodig, afhankelijk van het belang van late correcties voor je applicatie.

Kies een interval door terug te redeneren vanaf de maximale tijd waarin je bedrijf een onjuiste lokale status kan verdragen. Houd rekening met wachtrijvertraging, aanvraagtijd, nieuwe pogingen en workercapaciteit; alleen het pollinginterval bepaalt niet de hersteltijd. Voeg jitter toe zodat veel zendingen niet op hetzelfde moment vervallen. Als de provider requestlimieten documenteert of een batchopzoeking aanbiedt, verwerk die beperkingen dan in het ontwerp in plaats van aan te nemen dat een ontwerp dat in een kleine test werkt ongewijzigd kan opschalen.

Houd de administratie van de scheduler gescheiden van de providerstatus. Velden zoals last_poll_attempt_at, last_successful_poll_at, next_poll_at en last_webhook_received_at beantwoorden verschillende vragen. Vooral een pollpoging die een time-out oplevert, mag de marker voor een succesvolle poll niet vooruitzetten.

Wanneer de API conditionele verzoeken, een gedocumenteerde wijzigingscursor of een updated-since-filter ondersteunt, beoordeel dan of dit onnodige overdracht vermindert zonder records te verbergen. HTTP definieert gedrag voor conditionele verzoeken, waaronder de response 304 Not Modified, maar een integratie mag dit alleen gebruiken als het relevante endpoint dit ondersteunt en de betekenis ervan duidelijk is. Een cursor is niet uitwisselbaar met een tijdstempel: controleer wat de cursor ordent, of hij aan een account of zending is gekoppeld en hoe hij zich gedraagt wanneer resultaten over meerdere pagina's worden verdeeld.

Reconciliëren zonder een nieuwere update terug te draaien

De meest voorkomende race is eenvoudig: een poll start, vervolgens komt een nieuwere webhook binnen en de poll retourneert een oudere momentopname. Als het pollresultaat zonder vergelijking als laatste wordt opgeslagen, gaat de lokale zending achteruit. Voorkom dit door de gebeurtenistijd of versie van de provider te controleren wanneer die betrouwbaar is, en door de vergelijking en schrijfactie voor elke zending atomair te maken.

Ga er niet van uit dat aankomsttijd de volgorde van gebeurtenissen weerspiegelt. Een laat afgeleverde webhook kan een oudere scan beschrijven, terwijl een latere API-response een correctie op een eerder gemelde gebeurtenis kan bevatten. Definieer afzonderlijke regels voor het invoegen in de tijdlijn en het selecteren van de huidige status. Een oude scan kan bijvoorbeeld in de geschiedenis thuishoren zonder de huidige status te vervangen. Een correctie van de provider kan vereisen dat een opgeslagen gebeurtenis wordt gewijzigd in plaats van dat er een nieuwe wordt toegevoegd. De juiste regel hangt af van de identificatoren, tijdstempels en revisiesignalen die de provider levert.

Als de provider geen betrouwbare versie- of ordeningswaarde biedt, wees dan voorzichtig. Vergelijk het volledige geretourneerde record met het lokale record, markeer tegenstrijdigheden en behandel een statuslabel niet als een universeel ordeningsschema. “Uitzondering”, “onderweg voor bezorging” en “bezorgd” vormen niet altijd een eenvoudige lineaire volgorde, vooral niet wanneer een vervoerder later een scan corrigeert. Bewaar de onbewerkte waarden van de provider naast een eventuele genormaliseerde status, zodat een medewerker onzekere gevallen kan beoordelen.

Neveneffecten vereisen dezelfde discipline als opslag. Een poll die “bezorgd” ontdekt, mag geen tweede bezorgmelding versturen als een webhook er al één heeft veroorzaakt. Maak meldingen en downstreamtaken idempotent op basis van een duurzame zakelijke sleutel, zoals een verzend-ID plus een gedefinieerde overgang of gebeurtenis-ID van de provider. Een database-update en een externe melding kunnen doorgaans niet als één automatische bewerking worden behandeld; een transactionele outbox of gelijkwaardig duurzaam werkrecord kan helpen waarborgen dat een vastgelegde wijziging wordt gevolgd door één gecontroleerde poging om het neveneffect te verwerken.

Voer een beperkte backfill uit na een storing

Routinepolling is geen vervanging voor een expliciete herstelprocedure. Wanneer een webhookendpoint, wachtrij of worker niet beschikbaar is geweest, bepaal je eerst de getroffen periode en set zendingen. Neem zendingen op die tijdens de storing actief waren, niet alleen zendingen die momenteel als actief zijn gemarkeerd: een zending kan tijdens de gemiste updates een eindstatus hebben bereikt.

Start de backfill ver genoeg vóór de vermoedelijke storing om rekening te houden met vertraagde levering en onzekerheid over het detectietijdstip. Deze overlap verwerkt bewust een deel van de bekende gegevens opnieuw; idempotentie maakt dat veiliger dan een hiaat laten bestaan. Verwerk resultaten in beheersbare batches, houd de voortgang duurzaam bij en bewaar mislukte items voor een nieuwe poging. Verhoog een backfill-checkpoint niet alleen omdat een pagina is opgevraagd. Verhoog het pas nadat de records van de pagina zijn verwerkt of expliciet als onopgelost zijn geregistreerd.

Als de API paginering aanbiedt, controleer dan de volgorde en het gedrag bij voortzetting voordat je een paginanummer of cursor als herstelcheckpoint gebruikt. Als de API alleen momentopnames per zending aanbiedt, stel je de lijst met getroffen zendingen samen uit je eigen records en reconcileer je elke zending afzonderlijk. Documenteer de beperking van deze methode: de resulterende huidige statussen kunnen correct zijn, ook al blijven sommige tussentijdse scans niet beschikbaar.

Test de storingsgevallen die je verwacht te herstellen

Een bruikbaar testplan gaat verder dan één webhook versturen en één API-response controleren. Test dubbele webhookleveringen, een oudere webhook die na een nieuwere aankomt, een pollresponse die na een webhook aankomt, gedeeltelijke API-fouten, herstarts van workers en een crash tussen het opslaan van de verzendstatus en het plannen van een melding. Controleer zowel het zichtbare verzendrecord als het register van neveneffecten.

Test ook een backfill na een storing met meer records dan in één batch passen. Controleer of het opnieuw starten van de taak veilig een kleine hoeveelheid werk herhaalt in plaats van records over te slaan. Wanneer de API historische gebeurtenissen retourneert, test je of dezelfde scan zowel in webhook- als in pollindeling verschijnt en of je deduplicatieregel deze herkent. Wanneer de API alleen momentopnames retourneert, controleer je of je interface een afgeleide tussentijdse gebeurtenis niet presenteert als een waargenomen vervoerderscan.

Operationele monitoring moet drie signalen onderscheiden: de gezondheid van webhookleveringen, de gezondheid van polling en de actualiteit van gegevens. Nuttige metingen zijn onder meer de ouderdom van de laatste succesvolle reconciliatie voor in aanmerking komende zendingen, het aantal onopgeloste afwijkingen, wachtrijleeftijd, API-foutpercentages en de omvang van een herstelachterstand. Alleen een gezond webhookendpoint bewijst niet dat de lokale verzendstatus actueel is.

Pas het draaiboek toe op een tracking-API

Begin voor een shipment-trackingintegratie met de gedocumenteerde identificatoren, webhookpayloads, responses van zendingopzoekingen, authenticatievereisten en requestbeperkingen van de provider. Als je de 17TRACK Tracking API gebruikt, raadpleeg dan de officiële API-documentatie voordat je de poller implementeert. Bevestig welke opzoek- en updatemechanismen voor jouw integratie beschikbaar zijn in plaats van aan te nemen dat elk account of endpoint historische replay, cursorgebaseerde backfill of conditionele verzoeken ondersteunt.

De implementatiekeuze is niet “webhooks of polling”. Gebruik webhooks om de normale updatevertraging te verminderen, polling om afwijkingen te detecteren en te herstellen die de beschikbare API kan onthullen, en een expliciete backfillprocedure voor incidenten. Leg de herstelgrens vast in je runbook: of het systeem de huidige status, de gebeurtenisgeschiedenis of beide kan herstellen. Die grens bepaalt of een gemiste update leidt tot een kortstondig verouderde weergave of tot een permanent hiaat in het record.

Veelgestelde vragen

Kan polling garanderen dat geen trackinggebeurtenissen worden gemist?

Nee. Een opzoeking van de huidige status kan aantonen dat de laatste status is gewijzigd, maar kan geen tussentijdse gebeurtenis herstellen die de API niet retourneert. Herstel van historische gebeurtenissen vereist een beschikbare gebeurtenisgeschiedenis en een betrouwbare manier om de items daarin te identificeren of te vergelijken.

Moet een webhook onmiddellijk een API-poll activeren?

Alleen wanneer de API-opzoeking informatie toevoegt die je applicatie nodig heeft, of wanneer de webhook bewust een wijzigingsmelding is en geen volledig record. Na elke webhook pollen kan onnodige verzoeken veroorzaken. Als de webhook voldoende betrouwbare gegevens bevat, verwerk je die rechtstreeks en laat je API-controles over aan geplande reconciliatie of gericht onderzoek.

Wat als de API-poll en webhook elkaar tegenspreken?

Vergelijk de tijdstempels, versies, identificatoren en betekenis van de payloads van de provider voordat je een huidige status selecteert. Bewaar beide waarnemingen. Als de provider geen betrouwbaar ordeningssignaal levert en de afwijking gevolgen heeft voor een belangrijke actie, markeer je de zending voor beoordeling in plaats van stilzwijgend de laatst aangekomen response te kiezen.

Wanneer moet polling stoppen voor een bezorgde zending?

Gebruik een gedocumenteerd beleid dat is gebaseerd op de vraag of late correcties van de vervoerder, bewijs van levering of downstreamworkflows belangrijk zijn voor je applicatie. Een status die op een eindstatus lijkt, bewijst op zichzelf niet dat de provider het record nooit meer zal bijwerken.

Hoe moet de poller omgaan met rate limiting?

Verminder de requestdruk, probeer opnieuw met backoff en respecteer een Retry-After-header wanneer de server die verstrekt. Geef prioriteit aan zendingen met de grootste herstelbehoefte in plaats van alle zendingen voortdurend tegelijk opnieuw te proberen. HTTP-semantiek definieert de response 429 Too Many Requests en het veld Retry-After; endpointspecifieke limieten moeten nog steeds in de documentatie van de provider worden gecontroleerd.

Bronnen