Så synkroniserar du missade Webhook-uppdateringar med periodisk API-pollning: en handbok för hybridsynkronisering
Använd webhooks för snabba uppdateringar och periodisk API-pollning för att kontrollera om din lokala försändelsepost fortfarande överensstämmer med leverantörens post. Det tillförlitliga mönstret är att lagra webhook-leveranser beständigt, stämma av mot API:et med stabila försändelseidentifierare och hantera båda vägarna genom samma idempotenta uppdateringslogik. Pollning kan reparera missade statusändringar, men den kan inte återskapa mellanliggande händelser om API:et faktiskt inte exponerar händelsehistorik.

Den här handlingsplanen är avsedd för ingenjörer och driftteam som ansvarar för att hålla ett orderhanteringssystem, en spårningssida eller en kundsupportvy synkroniserad med försändelsedata. Dess centrala regel är enkel: behandla en webhook som en signal om att inspektera och bearbeta en ändring, inte som ett bevis på att alla tidigare ändringar har kommit fram.
Definiera vad ”synkroniserad” betyder innan du väljer ett intervall
En försändelseintegration kan behöva bevara två olika saker: det aktuella tillståndet, exempelvis ”under transport” eller ”levererad”, och den händelsehistorik som förklarar hur försändelsen hamnade där. En leverantörs sökning efter en försändelse kan returnera det senaste tillståndet, en lista över spårningshändelser eller båda. Dessa API-strukturer leder till olika garantier för återställning.
Om sökningen endast returnerar en ögonblicksbild av det aktuella tillståndet kan en avstämningspollning korrigera din lokala status efter en missad webhook. Den kan inte bevisa vilka mellanliggande statusar som inträffade. Om API:et returnerar historiska händelser med stabila identifierare eller tidsstämplar kan pollningen även återställa saknade tidslinjeposter. Kontrollera leverantörens faktiska svarsschema innan du lovar något av dessa resultat till användare längre ned i kedjan.
Skriv ned vilka fält din applikation måste stämma av: försändelseidentifierare, transportör eller spårningsidentifierare, normaliserad status, leverantörens status, händelsetid, tidpunkt för leverantörens senaste uppdatering, leveransuppgifter och eventuella fält som används för att utlösa kundmeddelanden. Separera fält som är auktoritativa hos leverantören från fält som ägs lokalt, till exempel en intern ärendeanteckning. Ett avstämningsjobb bör inte skriva över lokala data bara för att de saknas i ett API-svar.
Skapa en gemensam bearbetningsväg för webhook- och pollningsresultat
Webhook-hanterare och pollningsarbetare bör inte implementera konkurrerande regler för statusändringar. Båda bör skapa en normaliserad observation och skicka den till en enda avstämningsfunktion. Funktionen validerar identiteten, jämför observationen med den lagrade försändelsen, skriver en säker uppdatering och registrerar varför ändringen gjordes.
- Ta emot och autentisera. Validera en webhook med leverantörens dokumenterade metod. Avvisa förfrågningar som inte klarar valideringen, men behåll tillräckligt med icke-känslig diagnostisk information för att utreda leveransproblem.
- Beständiglagra före bekräftelse. Lägg en giltig leverans i beständig lagring eller en kö innan du returnerar framgång. Ett lyckat HTTP-svar som skickas före beständig lagring skapar ett glapp som en ny leverantörsförsökning kanske inte kan reparera.
- Normalisera. Mappa leverantörens nyttolast eller API-svar till en gemensam intern struktur, samtidigt som de ursprungliga leverantörsvärdena bevaras för utredning.
- Stäm av. Använd en stabil försändelsenyckel och en idempotensregel för att förhindra dubbla tidslinjeposter, upprepade aviseringar och onödiga skrivningar.
- Granska resultatet. Registrera om observationen ändrade försändelsen, redan var känd, var äldre än det lagrade tillståndet eller behöver manuell granskning.
Ett leverantörshändelse-ID är användbart för deduplicering om ett sådant finns och är stabilt. Om det inte finns kan en sammansatt nyckel behövas, men dess komponenter måste passa leverantörens datamodell. Två legitima skanningar kan ha samma status och tidsstämpel, så en nyckel som enbart bygger på dessa fält kan kasta bort en verklig händelse. Behåll den råa nyttolasten eller en referens till den under en definierad lagringsperiod så att tvetydiga matchningar kan utredas.
Utforma pollningsloopen utifrån risk, inte en enda global timer
Att polla alla kända försändelser med samma frekvens slösar med förfrågningar och kan belasta API-begränsningar. Underhåll en mängd försändelser som är berättigade till avstämning och välj dem utifrån operativ risk. En nyregistrerad försändelse som inte har fått sin första uppdatering, en försändelse med ett nyligt fel vid webhook-bearbetning och en försändelse vars status inte har ändrats inom det förväntade arbetsflödet kan behöva olika scheman. En slutförd försändelse kan behöva endast en begränsad slutkontroll, beroende på om sena korrigeringar är viktiga för din applikation.
Välj ett intervall genom att utgå från den maximala tid som verksamheten kan tolerera en felaktig lokal status. Ta hänsyn till köfördröjning, förfrågningstid, omförsök och arbetarkapacitet; själva pollningsintervallet är inte återställningstiden. Lägg till jitter så att många försändelser inte förfaller samtidigt. Om leverantören dokumenterar förfrågningsbegränsningar eller erbjuder en batchsökning ska du ta med dessa begränsningar i beräkningen, i stället för att anta att en design som fungerar i ett litet test kommer att skala oförändrad.
Håll schemaläggarens bokföring åtskild från leverantörens tillstånd. Fält som last_poll_attempt_at, last_successful_poll_at, next_poll_at och last_webhook_received_at besvarar olika frågor. I synnerhet får en pollning som timeoutar inte uppdatera markören för lyckad pollning.
När API:et stöder villkorade förfrågningar, en dokumenterad ändringsmarkör eller ett uppdaterad-sedan-filter bör du utvärdera om detta minskar onödig överföring utan att dölja poster. HTTP definierar beteendet för villkorade förfrågningar, inklusive svaret 304 Not Modified, men en integration bör endast använda det om den relevanta slutpunkten stöder det och semantiken är tydlig. En markör kan inte ersättas med en tidsstämpel: bekräfta vad den ordnar, om den är begränsad till ett konto eller en försändelse och hur den beter sig när resultaten pagineras.
Stäm av utan att rulla tillbaka en nyare uppdatering
Den vanligaste kapplöpningen är enkel: en pollning startar, sedan anländer en nyare webhook, och pollningen returnerar en äldre ögonblicksbild. Om pollningsresultatet skrivs sist utan jämförelse går den lokala försändelsen bakåt. Förhindra detta genom att kontrollera leverantörens händelsetid eller version när dessa är tillförlitliga och genom att göra jämförelsen och skrivningen atomiska för varje försändelse.
Anta inte att ankomsttiden återspeglar händelseordningen. En webhook som levereras sent kan beskriva en äldre skanning, medan ett senare API-svar kan innehålla en korrigering av en tidigare rapporterad händelse. Definiera separata regler för införande i tidslinjen och val av aktuellt tillstånd. En gammal skanning kan till exempel höra hemma i historiken utan att ersätta den aktuella statusen. En leverantörskorrigering kan kräva att en lagrad händelse ändras i stället för att en ny läggs till. Den korrekta regeln beror på vilka identifierare, tidsstämplar och revisionssignaler leverantören tillhandahåller.
Om leverantören inte erbjuder något tillförlitligt versions- eller ordningsfält bör du vara försiktig. Jämför hela den returnerade posten med den lokala posten, markera motsägelser och undvik att behandla en statusetikett som ett universellt ordningssystem. ”Undantag”, ”ute för leverans” och ”levererad” bildar inte alltid en enkel linjär sekvens, särskilt när en transportör senare korrigerar en skanning. Behåll leverantörens råvärden tillsammans med eventuell normaliserad status så att en människa kan granska osäkra fall.
Biverkningar kräver samma disciplin som lagring. En pollning som upptäcker ”levererad” bör inte skicka en andra leveransavisering om en webhook redan har utlöst en. Gör aviseringar och jobb längre ned i kedjan idempotenta mot en beständig affärsnyckel, exempelvis en försändelseidentifierare plus en definierad övergång eller ett leverantörshändelse-ID. En databasuppdatering och en extern avisering kan i allmänhet inte behandlas som en enda automatisk åtgärd; en transaktionell outbox eller en motsvarande beständig arbetspost kan bidra till att säkerställa att en bekräftad ändring följs av ett kontrollerat försök att behandla dess biverkning.
Kör en begränsad återfyllnad efter ett avbrott
Rutinmässig pollning ersätter inte en uttrycklig återställningsprocedur. När en webhook-slutpunkt, kö eller arbetare har varit otillgänglig ska du först identifiera den berörda perioden och mängden försändelser. Inkludera försändelser som var aktiva under avbrottet, inte bara de som för närvarande är markerade som aktiva: en försändelse kan ha nått ett slutligt tillstånd medan uppdateringar missades.
Starta återfyllnaden tillräckligt långt före det misstänkta felet för att ta hänsyn till fördröjd leverans och osäkerhet i tidpunkten då felet upptäcktes. Denna överlappning bearbetar avsiktligt vissa redan kända data igen; idempotens gör det säkrare än att lämna ett glapp. Bearbeta resultaten i hanterbara batcher, följ upp framstegen beständigt och behåll misslyckade poster för omförsök. Flytta inte en återfyllnadskontrollpunkt enbart för att en sida har begärts. Flytta den först efter att sidans poster har bearbetats eller uttryckligen registrerats som olösta.
Om API:et erbjuder paginering ska du verifiera dess ordning och fortsättningsbeteende innan du använder ett sidnummer eller en markör som återställningskontrollpunkt. Om det endast erbjuder ögonblicksbilder per försändelse ska du skapa listan över berörda försändelser från dina egna poster och stämma av var och en. Dokumentera begränsningen med denna metod: de resulterande aktuella statusarna kan vara korrekta även om vissa mellanliggande skanningar fortfarande saknas.
Testa de felsituationer som du förväntar dig att reparera
En användbar testplan går längre än att skicka en webhook och kontrollera ett API-svar. Testa dubbla webhook-leveranser, en äldre webhook som anländer efter en nyare, ett pollningssvar som anländer efter en webhook, partiella API-fel, omstarter av arbetare och en krasch mellan att försändelsetillståndet sparas och en avisering schemaläggs. Verifiera både den synliga försändelseposten och registret över biverkningar.
Testa även en återfyllnad efter ett avbrott med fler poster än vad som ryms i en batch. Bekräfta att en omstart av jobbet upprepar en liten mängd arbete på ett säkert sätt i stället för att hoppa över poster. Där API:et returnerar historiska händelser ska du testa om samma skanning förekommer både i webhook- och pollningsformat och om din dedupliceringsregel känner igen den. Där API:et endast returnerar ögonblicksbilder ska du bekräfta att gränssnittet inte visar en härledd mellanliggande händelse som en observerad transportörsskanning.
Operativ övervakning bör skilja mellan tre signaler: webhook-leveransens hälsa, pollningens hälsa och dataaktualitet. Användbara mätvärden omfattar åldern på den senaste lyckade avstämningen för berättigade försändelser, antalet olösta avvikelser, köålder, API-felfrekvenser och storleken på en återställningskö. En frisk webhook-slutpunkt i sig visar inte att det lokala försändelsetillståndet är aktuellt.
Tillämpa handlingsplanen på ett spårnings-API
För en försändelsespårningsintegration ska du börja med leverantörens dokumenterade identifierare, webhook-nyttolaster, svar från försändelsesökningar, autentiseringskrav och förfrågningsbegränsningar. Om du använder 17TRACK:s Tracking API ska du läsa dess officiella API-dokumentation innan du implementerar pollaren. Bekräfta vilka sök- och uppdateringsmekanismer som är tillgängliga för din integration i stället för att anta att varje konto eller slutpunkt stöder historisk uppspelning, markörbaserad återfyllnad eller villkorade förfrågningar.
Implementeringsbeslutet är inte ”webhooks eller pollning”. Använd webhooks för att minska den normala uppdateringsfördröjningen, pollning för att upptäcka och reparera avvikelser som det tillgängliga API:et kan visa och en uttrycklig återfyllnadsprocedur för incidenter. Ange återställningsgränsen i din driftmanual: om systemet kan återställa aktuell status, händelsehistorik eller båda. Den gränsen avgör om en missad uppdatering leder till en kortvarigt inaktuell vy eller ett permanent glapp i posten.
Vanliga frågor
Kan pollning garantera att inga spårningshändelser missas?
Nej. En sökning efter aktuellt tillstånd kan visa att den senaste statusen har ändrats, men den kan inte återställa en mellanliggande händelse som API:et inte returnerar. Återställning av historiska händelser kräver en tillgänglig händelsehistorik och ett tillförlitligt sätt att identifiera eller jämföra dess poster.
Bör en webhook utlösa en omedelbar API-pollning?
Endast när API-sökningen tillför information som din applikation behöver eller när webhooken avsiktligt är en ändringsavisering snarare än en komplett post. Pollning efter varje webhook kan skapa överflödiga förfrågningar. Om webhooken innehåller tillräckligt tillförlitliga data ska du bearbeta dem direkt och lämna API-kontroller till schemalagd avstämning eller riktad utredning.
Vad händer om API-pollningen och webhooken inte överensstämmer?
Jämför leverantörens tidsstämplar, versioner, identifierare och betydelsen av nyttolasterna innan du väljer ett aktuellt tillstånd. Bevara båda observationerna. Om leverantören inte tillhandahåller någon tillförlitlig ordningssignal och oenigheten påverkar en betydelsefull åtgärd ska du flagga försändelsen för granskning i stället för att tyst välja det svar som anlände sist.
När bör pollningen upphöra för en levererad försändelse?
Använd en dokumenterad policy baserad på om sena korrigeringar från transportören, leveransbevis eller arbetsflöden längre ned i kedjan är viktiga för din applikation. En status som ser slutgiltig ut innebär inte i sig att leverantören aldrig kommer att uppdatera posten igen.
Hur bör pollaren hantera hastighetsbegränsning?
Minska trycket på förfrågningarna, försök igen med exponentiell fördröjning och följ en Retry-After-header när servern tillhandahåller en sådan. Prioritera försändelser med störst återställningsbehov i stället för att upprepade gånger försöka med alla försändelser samtidigt. HTTP-semantiken definierar svaret 429 Too Many Requests och fältet Retry-After; slutpunktsspecifika begränsningar måste fortfarande kontrolleras i leverantörens dokumentation.
Källor
- RFC 9110: HTTP Semantics — villkorade förfrågningar,
304 Not Modified,429 Too Many RequestsochRetry-After. - 17TRACK Tracking API — officiell produktreferens för integrationer av försändelsespårning.
- 17TRACK API Documentation — officiell referens för verifiering av slutpunktsbeteende och integrationskrav.


