Skip to main content
HemBloggGuiderVad ska en spårnings-webhook-endpoint returnera? Statuskoder, tidsgränser och nya försök?

Vad ska en spårnings-webhook-endpoint returnera? Statuskoder, tidsgränser och nya försök?

17TRACK

En tracking-webhook-endpoint bör returnera ett snabbt och avsiktligt 2xx-svar efter att den har accepterat händelsen för behandling. I de flesta integrationer är det säkraste mönstret att autentisera begäran, validera nyttolasten, lagra eller köa händelsen och bekräfta den med 200 OK eller 202 Accepted. Använd 4xx-svar för begäranden som avsändaren inte bör försöka igen och 5xx-svar när ett tillfälligt problem på serversidan förhindrade att begäran accepterades. Det exakta timeout- och återförsöksbeteendet beror fortfarande på webhook-leverantörens avtal, så implementationen bör utformas utifrån dokumenterat avsändarbeteende snarare än antaganden.

Vilka statuskoder och timeout-värden bör en tracking-webhook-endpoint returnera

För en webhook för tracking eller leveransstatus är denna åtskillnad viktig eftersom leveranshändelser kan anlända mer än en gång, i fel ordning eller spelas upp igen efter ett nätverksfel. Endpointens uppgift är inte nödvändigtvis att slutföra alla affärsoperationer innan den svarar. Dess första uppgift är att fatta ett tillförlitligt beslut om huruvida händelsen har accepterats.

Svarskontraktet i praktiken

Ett webhook-svar har två målgrupper: det sändande systemet och din egen applikation. Avsändaren behöver ett tydligt HTTP-resultat för att kunna avgöra om leveransen ska markeras som lyckad, försöka igen eller stoppas. Din applikation behöver tillräckligt med tid för att verifiera och varaktigt registrera händelsen. Dessa mål är lättare att uppnå när endpointen har en kort synkron väg och en separat asynkron behandlingsväg.

  1. Ta emot HTTP-begäran över HTTPS.
  2. Kontrollera signaturen, autentiseringsuppgifterna, tidsstämpeln eller andra kontroller av begärans integritet som leverantören kräver.
  3. Parsa och validera nyttolasten utan att utföra långsamt efterföljande arbete.
  4. Skriv händelsen, eller en dedupliceringspost och händelsereferens, till varaktig lagring eller en tillförlitlig kö.
  5. Returnera ett avsiktligt 2xx-svar.
  6. Behandla trackinguppdateringen, kundmeddelandet, lagerändringen eller annan affärsåtgärd asynkront.

Ett svar bör inte hävda att händelsen har accepterats om den endast finns i processminnet. Om applikationen kraschar direkt efter att den har returnerat ett lyckat svar kan en händelse som aldrig sparades gå förlorad medan avsändaren tror att leveransen lyckades. Den tidpunkt då du returnerar 2xx bör därför överensstämma med din faktiska garanti för varaktighet.

Vilken statuskod bör en webhook returnera?

SvarBetydelse för avsändarenTypisk användning för webhook
200 OKBegäran accepterades och hanterades framgångsrikt.Ett praktiskt standardval efter validering och varaktigt accepterande.
202 AcceptedBegäran accepterades för behandling, men arbetet kan fortsätta.Användbart när händelsen har köats säkert men affärsbehandlingen sker asynkront.
204 No ContentBegäran lyckades och ingen svarskropp behövs.Lämpligt när leverantören accepterar ett tomt lyckat svar.
400–499Begäran är ogiltig, obehörig eller inte acceptabel i den form den skickades.Felaktig nyttolast, misslyckad autentisering, ogiltig signatur eller en permanent avvisad händelse.
429 Too Many RequestsMottagaren tillämpar hastighetsbegränsning.Använd endast när avsändarens återförsöksbeteende och din policy för hastighetsbegränsning är kompatibla.
500–599Mottagaren kunde inte acceptera begäran på grund av ett server- eller tillfälligt problem.Databasavbrott, köfel, beroendefel eller ett oväntat applikationsfel.

200 OK är ofta det minst överraskande valet eftersom det allmänt förstås som ett lyckat mottagande. 202 Accepted är också semantiskt användbart när endpointen har accepterat händelsen för senare behandling. Ingen av koderna är automatiskt rätt: avsändarens dokumentation kan ange vilka 2xx-svar som räknas som lyckade, och vissa leverantörer kan förvänta sig en viss svarskropp eller innehållstyp.

Returnera inte ett 2xx-svar enbart för att HTTP-begäran nådde din server. Om signaturverifieringen misslyckas eller nyttolasten inte kan tolkas på ett säkert sätt är ett 4xx-svar vanligtvis mer korrekt. Returnera däremot inte 4xx vid ett tillfälligt databasavbrott om händelsen kan lyckas senare. Ett 5xx-svar ger en avsändare som kan försöka igen möjlighet att leverera händelsen på nytt, även om leverantören kan tillämpa sin egen policy.

Hur bör timeouts hanteras?

Webhook-timeoutvärden är specifika för varje leverantör. Det finns ingen universell HTTP-timeout som används av alla trackingplattformar, och en avsändare kan sluta vänta innan din applikation har slutfört en långsam operation. Betrakta avsändarens dokumenterade timeout som en övre gräns, inte som ett mål. Din endpoint bör normalt svara långt före denna gräns.

Det vanligaste designfelet är att utföra allt efterföljande arbete innan webhooken bekräftas. En hanterare kan anropa en databas, ett orderhanteringssystem, en aviseringstjänst och en analysprocess i följd. Ett långsamt beroende kan få avsändaren att se en timeout även om applikationen så småningom slutför arbetet. Avsändaren kan då försöka igen, vilket skapar dubbel behandling eller konkurrerande uppdateringar.

Begränsa den synkrona vägen till det arbete som behövs för att fatta ett säkert beslut om accepterande. Det omfattar vanligtvis autentisering av begäran, grundläggande schemavalidering, varaktig lagring av händelsen och publicering i en kö. Placera kostsam berikning, uppslag hos transportörer, kundmeddelanden och API-anrop till tredje part bakom en worker. Övervaka separat tiden för mottagning, validering, lagring och bekräftelse av händelsen samt tiden för själva behandlingen.

En timeout är inte samma sak som en misslyckad affärsoperation. Ur avsändarens perspektiv innebär en timeout vanligtvis att den inte fick ett användbart lyckat svar. Din tjänst kan ha sparat händelsen precis innan anslutningen stängdes. Därför krävs idempotens och deduplicering även när endpointen verkar tillförlitlig.

Vad orsakar återförsök?

En webhook-avsändare kan försöka igen efter ett anslutningsfel, en timeout eller ett svar som dess avtal klassificerar som misslyckat. Det exakta schemat, maximala antalet försök, backoff-algoritmen och leveransfönstret varierar mellan leverantörer. Lova inte ett fast antal återförsök om det inte anges i leverantörens dokumentation.

Mottagaren bör anta att återförsök kan inträffa och utforma systemet för dem medvetet:

  • Använd en händelseidentifierare när den finns tillgänglig. Lagra den med en unik begränsning eller en motsvarande dedupliceringsnyckel.
  • Gör behandlingen idempotent. Att tillämpa samma leveransstatusuppdatering två gånger bör inte skicka två kundmeddelanden, skapa två återbetalningar eller flytta en order felaktigt.
  • Behåll den ursprungliga nyttolasten eller en användbar revisionspost. Detta stöder uppspelning, utredning och avstämning.
  • Separera accepterande från behandling. En worker kan försöka igen vid interna fel utan att tvinga avsändaren att upprepa hela HTTP-utbytet.
  • Registrera svarskoder och fördröjning. En ökning av 5xx-svar, timeouts eller dubbla händelse-ID:n kan avslöja ett avbrott innan användare rapporterar saknade trackinguppdateringar.

En dubbletthändelse bör vanligtvis få ett lyckat svar om den ursprungliga händelsen redan har accepterats varaktigt. Att returnera ett fel för varje dubblett kan utlösa onödiga återförsök. Endpointen kan registrera att händelsen har setts tidigare, hoppa över den upprepade affärsåtgärden och returnera samma lyckade svarsklass som används för en nyligen accepterad händelse.

När bör du returnera 4xx, 429 eller 5xx?

Returnera 4xx när det är osannolikt att ett nytt försök med samma begäran löser problemet. Exempel är en ogiltig signatur, saknad obligatorisk autentisering, en payloadstruktur som inte stöds eller en begäran som bryter mot en permanent valideringsregel. Kontrollera innan du väljer 4xx om avsändaren behandlar statusen som ett permanent fel. Vissa plattformar har egna regler för misslyckade leveranser.

Använd 429 försiktigt. HTTP definierar 429 för hastighetsbegränsning, och headern Retry-After kan ange när ett nytt försök kan vara lämpligt. Alla webhook-avsändare tolkar dock inte 429 på samma sätt. Om kön är full eller tjänsten är överbelastad bör du bekräfta att leverantören försöker igen på ett säkert sätt och att dess schema inte förvärrar överbelastningen. En begränsad mottagningskö och en plan för mottryck är vanligtvis bättre än att låta begäranden misslyckas oförutsägbart.

Returnera 5xx när mottagaren inte kan acceptera händelsen på ett säkert sätt på grund av ett tillfälligt problem. Detta omfattar en otillgänglig databas, en misslyckad skrivning till en varaktig kö eller ett internt fel som förhindrade validering eller lagring. Att returnera 200 samtidigt som händelsen tyst ignoreras gör återställning svårare eftersom avsändaren inte har någon anledning att försöka igen.

Undvik att förlita dig på omdirigeringar som 301, 302 eller 307 för webhook-leverans. Omdirigeringshantering skiljer sig mellan klienter, och att omdirigera en signerad begäran kan skapa oklarhet kring destination, metod och kropp. Konfigurera i stället leverantören med den slutliga HTTPS-endpointen.

En tillförlitlig svarspolicy för trackinghändelser

För de flesta tracking-webhook-integrationer är följande policy en rimlig utgångspunkt:

  1. Returnera 200 eller 202 efter att händelsen har passerat autentisering och lagrats varaktigt eller placerats i en tillförlitlig kö.
  2. Returnera ett 4xx-svar för ogiltig signatur, ogiltig autentisering eller en permanent oanvändbar nyttolast enligt leverantörens dokumenterade regler.
  3. Returnera 5xx när ett tillfälligt fel förhindrar varaktigt accepterande.
  4. Returnera ett lyckat svar för en säkert identifierad dubblett och förhindra samtidigt dubbla affärseffekter.
  5. Håll hanteraren snabb och mät dess bekräftelsefördröjning.
  6. Testa scenarier med timeout, återförsök, dubbletter, felaktig ordning, felaktig nyttolast och leverantörsavbrott före produktionslansering.

Om du integrerar ett tracking-API bör du börja med leverantörens webhook-dokumentation och bekräfta accepterade lyckade koder, metod för signering av begäran, timeout, återförsöksutlösare, payloadschema och händelseidentifierare. För 17TRACK-integrationer är den officiella dokumentationen för Tracking API rätt plats för att kontrollera det leverantörsspecifika avtalet i stället för att dra slutsatser utifrån allmän HTTP-praxis.

Implementeringschecklista

  • Endpointen är nåbar över HTTPS och har en stabil produktions-URL.
  • Autentisering och signaturverifiering sker före affärsbehandlingen.
  • Den råa begäran eller en verifierbar representation sparas där det krävs för signaturkontroller och felsökning.
  • Händelsen sparas innan det lyckade svaret skickas.
  • Dubblettleveranser är säkra och upprepar inte oåterkalleliga åtgärder.
  • Workers kan försöka igen med intern behandling oberoende av avsändarens HTTP-återförsökscykel.
  • Loggar innehåller händelse-ID, leveranstid, svarskod, behandlingsstatus och korrelations-ID utan att hemligheter exponeras.
  • Aviseringar skiljer mellan timeout för endpointen, 4xx-valideringsfel, 5xx-avbrott, köfördröjningar och dubblettleveranser.
  • Leverantörens dokumenterade beteende har testats med verkliga händelser eller sandboxhändelser.

Vanliga frågor

Är 200 OK bättre än 202 Accepted för en webhook?

Ingen av dem är universellt bättre. Använd 200 OK när begäran har accepterats och din integration behandlar svaret som ett allmänt lyckat svar. Använd 202 Accepted när händelsen har accepterats för asynkron behandling. Bekräfta att avsändaren klassificerar det valda 2xx-svaret som lyckat.

Bör en webhook-endpoint vänta tills trackinguppdateringen är helt behandlad?

Vanligtvis inte. Den bör endast vänta tills händelsen har autentiserats, validerats och accepterats varaktigt. Långvarigt arbete bör normalt ske efter bekräftelsen så att ett långsamt beroende inte orsakar en timeout och ett återförsök som hade kunnat undvikas.

Vad bör hända när samma trackinghändelse anländer två gånger?

Identifiera den med leverantörens händelse-ID eller en noggrant utformad motsvarande nyckel, hoppa över dubbla sidoeffekter och returnera ett lyckat svar om händelsen redan har accepterats. Detta gör återförsök säkra utan att dölja nya behandlingsfel.

Bör en ogiltig signatur returnera 400 eller 401?

Valet beror på din autentiseringsmodell och leverantörens dokumenterade förväntningar. Båda kan kommunicera avvisande, men konsekvens är viktigare än att välja en kod som gäller universellt. Bekräfta inte en händelse vars äkthet du inte kan verifiera.

Orsakar ett 5xx-svar alltid ett återförsök?

Nej. Många webhook-system försöker igen vid timeouts och serverfel, men utlösare och scheman för återförsök är specifika för varje leverantör. Betrakta återförsök som ett dokumenterat integrationsbeteende och verifiera dem i en testmiljö.

Källor