Skip to main content
HjemBlogVejledningerHvad skal et tracking-webhook-endpoint returnere? Statuskoder, timeouts og genforsøg?

Hvad skal et tracking-webhook-endpoint returnere? Statuskoder, timeouts og genforsøg?

17TRACK

Et tracking-webhook-endpoint bør returnere et hurtigt, bevidst 2xx-svar, efter at det har accepteret hændelsen til behandling. I de fleste integrationer er det sikreste mønster at godkende anmodningen, validere payloaden, gemme eller sætte hændelsen i kø og bekræfte den med 200 OK eller 202 Accepted. Brug 4xx-svar til anmodninger, som afsenderen ikke bør forsøge igen, og 5xx-svar, når et midlertidigt problem på serversiden forhindrede accept. Den præcise timeout- og genforsøgsadfærd afhænger stadig af webhook-udbyderens kontrakt, så din implementering bør være baseret på dokumenteret afsenderadfærd frem for antagelser.

Hvilke statuskoder og timeouts bør et tracking-webhook-endpoint returnere

For en webhook til tracking eller forsendelsesstatus er denne sondring vigtig, fordi leveringshændelser kan ankomme mere end én gang, ankomme i uordnet rækkefølge eller blive afspillet efter en netværksfejl. Endpointets opgave er ikke nødvendigvis at fuldføre alle forretningshandlinger, før det svarer. Den første opgave er at træffe en pålidelig beslutning om, hvorvidt hændelsen er blevet accepteret.

Svarskontrakten i praksis

Et webhook-svar har to modtagere: det afsendende system og din egen applikation. Afsenderen har brug for et tydeligt HTTP-resultat for at kunne beslutte, om leveringen skal markeres som vellykket, forsøges igen eller stoppes. Din applikation har brug for tilstrækkelig tid til at verificere og gemme hændelsen permanent. Disse mål er lettere at opfylde, når endpointet har en kort synkron sti og en separat asynkron behandlingssti.

  1. Modtag HTTP-anmodningen over HTTPS.
  2. Kontrollér signaturen, godkendelsesoplysningerne, tidsstemplet eller andre kontroller af anmodningens integritet, som udbyderen kræver.
  3. Parse og validér payloaden uden at udføre langsomt downstream-arbejde.
  4. Skriv hændelsen eller en deduplikeringspost og en hændelsesreference til permanent lager eller en pålidelig kø.
  5. Returnér et bevidst 2xx-svar.
  6. Behandl trackingopdateringen, kundemeddelelsen, lagerændringen eller en anden forretningshandling asynkront.

Et svar bør ikke hævde accept, hvis hændelsen kun findes i processens hukommelse. Hvis applikationen går ned umiddelbart efter et succesfuldt svar, kan en hændelse, der aldrig blev gemt permanent, gå tabt, mens afsenderen tror, at leveringen lykkedes. Det tidspunkt, hvor du returnerer 2xx, bør derfor stemme overens med din faktiske garanti for datalagring.

Hvilken statuskode bør en webhook returnere?

SvarBetydning for afsenderenTypisk brug af webhook
200 OKAnmodningen blev accepteret og behandlet korrekt.Et praktisk standardvalg efter validering og permanent accept.
202 AcceptedAnmodningen blev accepteret til behandling, men arbejdet kan fortsætte.Nyttigt, når hændelsen er sat sikkert i kø, men forretningsbehandlingen er asynkron.
204 No ContentAnmodningen lykkedes, og der er ikke brug for en svarbody.Egnet, når udbyderen accepterer et tomt succesfuldt svar.
400–499Anmodningen er ugyldig, uautoriseret eller ikke acceptabel i den sendte form.Forkert payload, mislykket godkendelse, ugyldig signatur eller en permanent afvist hændelse.
429 Too Many RequestsModtageren anvender hastighedsbegrænsning.Brug kun, når afsenderens genforsøgsadfærd og din politik for hastighedsbegrænsning er kompatible.
500–599Modtageren kunne ikke acceptere anmodningen på grund af et serverproblem eller et midlertidigt problem.Databaseudfald, køfejl, fejl i en afhængighed eller en uventet applikationsfejl.

200 OK er ofte det mindst overraskende valg, fordi det bredt forstås som en vellykket modtagelse. 202 Accepted er også semantisk nyttigt, når endpointet har accepteret hændelsen til senere behandling. Ingen af koderne er automatisk korrekte: Afsenderens dokumentation kan definere, hvilke 2xx-svar der tæller som succesfulde, og nogle udbydere kan forvente en bestemt body eller indholdstype.

Returnér ikke et 2xx-svar blot fordi HTTP-anmodningen nåede din server. Hvis signaturverifikationen mislykkes, eller payloaden ikke kan fortolkes sikkert, er et 4xx-svar normalt mere retvisende. Omvendt bør du ikke returnere 4xx ved et midlertidigt databaseudfald, hvis hændelsen kan lykkes senere. Et 5xx-svar giver en afsender, der understøtter genforsøg, mulighed for at levere hændelsen igen, selv om udbyderen kan anvende sin egen politik.

Hvordan bør timeouts håndteres?

Webhook-timeoutværdier er specifikke for udbyderen. Der findes ingen universel HTTP-timeout, som alle trackingplatforme anvender, og en afsender kan holde op med at vente, før din applikation afslutter en langsom handling. Betragt afsenderens dokumenterede timeout som en maksimal grænse, ikke som et mål. Dit endpoint bør normalt svare længe før denne grænse.

Den mest almindelige designfejl er at udføre alt downstream-arbejde, før webhooken bekræftes. En handler kan kalde en database, et ordrebehandlingssystem, en notifikationstjeneste og en analysepipeline efter hinanden. Én langsom afhængighed kan få afsenderen til at se en timeout, selv om din applikation til sidst fuldfører arbejdet. Afsenderen kan derefter forsøge igen, hvilket skaber dobbelt behandling eller konkurrerende opdateringer.

Begræns den synkrone sti til det arbejde, der er nødvendigt for at træffe en sikker acceptbeslutning. Det omfatter normalt godkendelse af anmodningen, grundlæggende skemavalidering, permanent lagring af hændelsen og publicering til en kø. Placér dyr berigelse, opslag hos transportører, kundemeddelelser og API-kald til tredjeparter bag en worker. Overvåg separat den tid, der bruges på at modtage, validere, gemme og bekræfte hændelsen, og den tid, der bruges på at behandle den.

En timeout er ikke det samme som en mislykket forretningshandling. Fra afsenderens perspektiv betyder en timeout normalt, at den ikke modtog et brugbart succesfuldt svar. Din tjeneste kan have gemt hændelsen korrekt, lige før forbindelsen blev lukket. Derfor er idempotens og deduplikering nødvendige, selv når endpointet virker pålideligt.

Hvad forårsager genforsøg?

En webhook-afsender kan forsøge igen efter en forbindelsesfejl, en timeout eller et svar, som dens kontrakt klassificerer som mislykket. Den præcise tidsplan, det maksimale antal forsøg, backoff-algoritmen og leveringsvinduet varierer efter udbyder. Lov ikke et fast antal genforsøg, medmindre det står i udbyderens dokumentation.

Modtageren bør antage, at genforsøg kan forekomme, og bevidst designe til dem:

  • Brug en hændelsesidentifikator, når den er tilgængelig. Gem den med en unik begrænsning eller en tilsvarende deduplikeringsnøgle.
  • Gør behandlingen idempotent. Den samme opdatering af leveringsstatus bør ikke sende to kundemeddelelser, oprette to refusioner eller flytte en ordre forkert frem.
  • Bevar den oprindelige payload eller en nyttig revisionspost. Det understøtter genafspilning, undersøgelse og afstemning.
  • Adskil accept fra behandling. En worker kan forsøge interne fejl igen uden at tvinge afsenderen til at gentage hele HTTP-udvekslingen.
  • Registrér svarskoder og latenstid. En stigning i 5xx-svar, timeouts eller duplikerede hændelses-ID'er kan afsløre et udfald, før brugerne rapporterer manglende trackingopdateringer.

En duplikeret hændelse bør normalt modtage et succesfuldt svar, hvis den oprindelige hændelse allerede er blevet accepteret permanent. At returnere en fejl for hver duplikat kan udløse unødvendige genforsøg. Endpointet kan registrere, at hændelsen tidligere er set, springe den gentagne forretningshandling over og returnere samme succesklasse, som bruges for en nyaccepteret hændelse.

Hvornår bør du returnere 4xx, 429 eller 5xx?

Returnér 4xx, når det sandsynligvis ikke løser problemet at forsøge den samme anmodning igen. Eksempler omfatter en ugyldig signatur, manglende obligatorisk godkendelse, en payloadstruktur, der ikke understøttes, eller en anmodning, der overtræder en permanent valideringsregel. Kontrollér, om afsenderen behandler statuskoden som en permanent fejl, før du vælger 4xx. Nogle platforme har egne regler for mislykkede leveringer.

Brug 429 med omtanke. HTTP definerer 429 til hastighedsbegrænsning, og headeren Retry-After kan angive, hvornår et genforsøg kan være passende. Ikke alle webhook-afsendere fortolker dog 429 på samme måde. Hvis din kø er fuld, eller din tjeneste er overbelastet, skal du bekræfte, at udbyderen vil forsøge sikkert igen, og at dens genforsøgsplan ikke forværrer overbelastningen. En begrænset indgående kø og en plan for backpressure er normalt bedre end at lade anmodninger mislykkes uforudsigeligt.

Returnér 5xx, når modtageren ikke sikkert kan acceptere hændelsen på grund af et midlertidigt problem. Det omfatter en utilgængelig database, en mislykket skrivning til en permanent kø eller en intern fejl, der forhindrede validering eller lagring. At returnere 200, mens hændelsen lydløst kasseres, gør genopretning vanskeligere, fordi afsenderen ikke har nogen grund til at forsøge igen.

Undgå at basere dig på omdirigeringer som 301, 302 eller 307 ved webhook-levering. Håndteringen af omdirigeringer varierer mellem klienter, og omdirigering af en signeret anmodning kan skabe uklarhed om destination, metode og body. Konfigurér i stedet udbyderen med det endelige HTTPS-endpoint.

En pålidelig svarpolitik for trackinghændelser

For de fleste tracking-webhook-integrationer er følgende politik et fornuftigt udgangspunkt:

  1. Returnér 200 eller 202, efter at hændelsen er godkendt og gemt permanent eller placeret i en pålidelig kø.
  2. Returnér et 4xx-svar for en ugyldig signatur, ugyldig godkendelse eller en permanent ubrugelig payload i overensstemmelse med udbyderens dokumenterede regler.
  3. Returnér 5xx, når en midlertidig fejl forhindrer permanent accept.
  4. Returnér et succesfuldt svar for en sikkert genkendt duplikat, samtidig med at du forhindrer duplikerede forretningseffekter.
  5. Hold handleren hurtig, og mål dens bekræftelseslatenstid.
  6. Test scenarier med timeout, genforsøg, duplikater, uordnet rækkefølge, fejlformat og udfald hos udbyderen før produktionslancering.

Hvis du integrerer en tracking-API, skal du begynde med udbyderens webhook-dokumentation og bekræfte de accepterede succesfulde koder, metoden til signering af anmodninger, timeout, genforsøgstriggere, payloadskema og hændelsesidentifikator. For 17TRACK-integrationer er den officielle Tracking API-dokumentation det rette sted at kontrollere den udbyderspecifikke kontrakt i stedet for at udlede den fra generel HTTP-praksis.

Implementeringstjekliste

  • Endpointet er tilgængeligt over HTTPS og har en stabil produktions-URL.
  • Godkendelse og signaturverifikation sker før forretningsbehandlingen.
  • Den rå anmodning eller en verificerbar repræsentation bevares, hvor det kræves til signaturkontrol og fejlfinding.
  • Hændelsen gemmes, før succesfuldt svar sendes.
  • Duplikerede leveringer er sikre og gentager ikke irreversible handlinger.
  • Workere kan forsøge intern behandling igen uafhængigt af afsenderens HTTP-genforsøgscyklus.
  • Logge indeholder hændelses-ID, leveringstidspunkt, svarskode, behandlingstilstand og korrelations-ID uden at afsløre hemmeligheder.
  • Alarmer skelner mellem endpoint-timeouts, 4xx-valideringsfejl, 5xx-udfald, køforsinkelser og duplikerede leveringer.
  • Den dokumenterede udbyderadfærd er testet med reelle hændelser eller sandkassehændelser.

FAQ

Er 200 OK bedre end 202 Accepted for en webhook?

Ingen af dem er universelt bedre. Brug 200 OK, når anmodningen er accepteret, og din integration behandler svaret som en generel succes. Brug 202 Accepted, når hændelsen er accepteret til asynkron behandling. Bekræft, at afsenderen klassificerer det valgte 2xx-svar som succesfuldt.

Bør et webhook-endpoint vente, indtil trackingopdateringen er fuldt behandlet?

Normalt ikke. Det bør kun vente, indtil hændelsen er godkendt, valideret og accepteret permanent. Langvarigt arbejde bør normalt udføres efter bekræftelsen, så en langsom afhængighed ikke forårsager en undgåelig timeout og et genforsøg.

Hvad skal der ske, når den samme trackinghændelse ankommer to gange?

Genkend den ved hjælp af udbyderens hændelses-ID eller en omhyggeligt udformet tilsvarende nøgle, spring duplikerede sideeffekter over, og returnér et succesfuldt svar, hvis hændelsen allerede er accepteret. Det gør genforsøg sikre uden at skjule nye behandlingsfejl.

Bør en ugyldig signatur returnere 400 eller 401?

Valget afhænger af din godkendelsesmodel og udbyderens dokumenterede forventninger. Begge kan kommunikere en afvisning, men ensartethed er vigtigere end at vælge én universel kode. Bekræft ikke en hændelse, hvis ægtheden ikke kan verificeres.

Forårsager et 5xx-svar altid et genforsøg?

Nej. Mange webhook-systemer forsøger igen ved timeouts og serverfejl, men genforsøgstriggere og tidsplaner er specifikke for udbyderen. Betragt genforsøg som en dokumenteret integrationsadfærd, og verificér den i et testmiljø.

Kilder