Hva skal et tracking-webhook-endepunkt returnere? Statuskoder, tidsavbrudd og nye forsøk?
Et endepunkt for en sporings-webhook bør returnere et raskt og bevisst 2xx-svar etter at det har godtatt hendelsen for behandling. I de fleste integrasjoner er det tryggeste mønsteret å autentisere forespørselen, validere nyttelasten, lagre eller legge hendelsen i en kø og bekrefte den med 200 OK eller 202 Accepted. Bruk 4xx-svar for forespørsler avsenderen ikke bør prøve på nytt, og 5xx-svar når et midlertidig problem på serversiden hindret godkjenning. Den nøyaktige tidsavbrudds- og oppførselslogikken for nye forsøk avhenger fortsatt av webhook-leverandørens avtale, så implementasjonen bør utformes rundt dokumentert avsenderatferd i stedet for antakelser.
For en webhook for sporing eller forsendelsesstatus er dette skillet viktig fordi leveringshendelser kan komme mer enn én gang, komme i feil rekkefølge eller bli avspilt på nytt etter en nettverksfeil. Endepunktets oppgave er ikke nødvendigvis å fullføre alle forretningsoperasjoner før det svarer. Den første oppgaven er å ta en pålitelig beslutning om hendelsen er godtatt.
Svaravtalen i praksis
Et webhook-svar har to målgrupper: avsendersystemet og din egen applikasjon. Avsenderen trenger et tydelig HTTP-resultat for å avgjøre om leveringen skal markeres som vellykket, prøves på nytt eller stoppes. Applikasjonen din trenger nok tid til å bekrefte og lagre hendelsen på en varig måte. Disse målene er enklere å oppnå når endepunktet har en liten synkron bane og en separat asynkron behandlingsbane.
- Motta HTTP-forespørselen over HTTPS.
- Kontroller signaturen, autentiseringsopplysningene, tidsstempelet eller andre kontroller av forespørselens integritet som leverandøren krever.
- Analyser og valider nyttelasten uten å utføre langsomt arbeid i etterfølgende systemer.
- Skriv hendelsen, eller en dedupliseringspost og en hendelsesreferanse, til varig lagring eller en pålitelig kø.
- Returner et bevisst 2xx-svar.
- Behandle sporingsoppdateringen, kundemeldingen, lagerendringen eller en annen forretningshandling asynkront.
Et svar bør ikke hevde at hendelsen er godtatt hvis den bare finnes i prosessminnet. Hvis applikasjonen krasjer umiddelbart etter at den returnerer suksess, kan en hendelse som aldri ble lagret gå tapt mens avsenderen tror leveringen var vellykket. Tidspunktet da du returnerer 2xx, bør derfor samsvare med den faktiske garantien for varig lagring.
Hvilken statuskode bør en webhook returnere?
| Respons | Betydning for avsenderen | Typisk bruk av webhook |
|---|---|---|
200 OK | Forespørselen ble godtatt og behandlet. | Et praktisk standardvalg etter validering og varig godkjenning. |
202 Accepted | Forespørselen ble godtatt for behandling, men arbeidet kan fortsette. | Nyttig når hendelsen er lagt trygt i kø, men forretningsbehandlingen skjer asynkront. |
204 No Content | Forespørselen var vellykket, og ingen svartekst er nødvendig. | Passer når leverandøren godtar et tomt suksessvar. |
400–499 | Forespørselen er ugyldig, uautorisert eller ikke akseptabel slik den ble sendt. | Feilformatert nyttelast, mislykket autentisering, ugyldig signatur eller en permanent avvist hendelse. |
429 Too Many Requests | Mottakeren bruker hastighetsbegrensning. | Bruk bare når avsenderens oppførsel ved nye forsøk og retningslinjene dine for hastighetsbegrensning er kompatible. |
500–599 | Mottakeren kunne ikke godta forespørselen på grunn av et problem på serversiden eller et midlertidig problem. | Databaseutfall, køfeil, feil i en avhengighet eller en uventet applikasjonsfeil. |
200 OK er ofte det minst overraskende valget fordi det er bredt forstått som vellykket mottak. 202 Accepted er også semantisk nyttig når endepunktet har godtatt hendelsen for senere behandling. Ingen av kodene er automatisk riktige: Avsenderens dokumentasjon kan angi hvilke 2xx-svar som regnes som vellykkede, og enkelte leverandører kan forvente en bestemt tekst eller innholdstype.
Ikke returner et 2xx-svar bare fordi HTTP-forespørselen nådde serveren din. Hvis signaturverifiseringen mislykkes eller nyttelasten ikke kan tolkes på en trygg måte, er et 4xx-svar vanligvis mer korrekt. Omvendt bør du ikke returnere 4xx ved et midlertidig databaseutfall hvis hendelsen kan lykkes senere. Et 5xx-svar gir en avsender som støtter nye forsøk mulighet til å levere hendelsen på nytt, selv om leverandøren kan ha sin egen policy.
Hvordan bør tidsavbrudd håndteres?
Verdier for tidsavbrudd for webhooks er leverandørspesifikke. Det finnes ikke ett universelt HTTP-tidsavbrudd som alle sporingsplattformer bruker, og en avsender kan slutte å vente før applikasjonen din er ferdig med en langsom operasjon. Betrakt avsenderens dokumenterte tidsavbrudd som en øvre grense, ikke som et mål. Endepunktet bør normalt svare i god tid før denne grensen.
Den vanligste designfeilen er å utføre alt etterfølgende arbeid før webhooken bekreftes. En behandler kan kalle en database, et ordrebehandlingssystem, en varslingstjeneste og en analysepipeline etter hverandre. Én langsom avhengighet kan føre til at avsenderen ser et tidsavbrudd selv om applikasjonen til slutt fullfører arbeidet. Avsenderen kan da prøve på nytt, noe som skaper duplikatbehandling eller konkurrerende oppdateringer.
Begrens den synkrone banen til arbeidet som trengs for å ta en trygg beslutning om godkjenning. Dette omfatter vanligvis autentisering av forespørselen, grunnleggende skjemavalidering, varig lagring av hendelsen og publisering til en kø. Legg kostbar berikelse, oppslag hos transportører, kundemeldinger og API-kall til tredjeparter bak en arbeider. Overvåk tiden som brukes på å motta, validere, lagre og bekrefte hendelsen separat fra tiden som brukes på å behandle den.
Et tidsavbrudd er ikke det samme som en mislykket forretningsoperasjon. Fra avsenderens perspektiv betyr et tidsavbrudd vanligvis at den ikke mottok et brukbart suksessvar. Tjenesten din kan ha lagret hendelsen vellykket like før forbindelsen ble avsluttet. Derfor kreves idempotens og deduplisering selv når endepunktet virker pålitelig.
Hva forårsaker nye forsøk?
En webhook-avsender kan prøve på nytt etter en tilkoblingsfeil, et tidsavbrudd eller et svar som avtalen klassifiserer som mislykket. Den nøyaktige tidsplanen, maksimale antall forsøk, algoritmen for tilbakeventing og leveringsperioden varierer etter leverandør. Ikke lov et fast antall nye forsøk med mindre det står i leverandørens dokumentasjon.
Mottakeren bør anta at nye forsøk kan skje, og utforme systemet bevisst for dette:
- Bruk en hendelses-ID når den er tilgjengelig. Lagre den med en unik begrensning eller en tilsvarende dedupliseringsnøkkel.
- Gjør behandlingen idempotent. Å bruke den samme leveringsstatusoppdateringen to ganger bør ikke sende to kundemeldinger, opprette to refusjoner eller flytte en ordre feil.
- Behold den opprinnelige nyttelasten eller en nyttig revisjonspost. Dette støtter avspilling, undersøkelse og avstemming.
- Skill godkjenning fra behandling. En arbeider kan prøve interne feil på nytt uten å tvinge avsenderen til å gjenta hele HTTP-utvekslingen.
- Registrer svarkoder og svartid. En økning i 5xx-svar, tidsavbrudd eller dupliserte hendelses-ID-er kan avsløre et utfall før brukerne melder om manglende sporingsoppdateringer.
En duplisert hendelse bør vanligvis få et vellykket svar hvis den opprinnelige hendelsen allerede er varig godtatt. Å returnere en feil for hver duplikat kan utløse unødvendige nye forsøk. Endepunktet kan registrere at hendelsen allerede er sett, hoppe over den gjentatte forretningshandlingen og returnere samme suksessklasse som brukes for en nygodtatt hendelse.
Når bør du returnere 4xx, 429 eller 5xx?
Returner 4xx når det er lite sannsynlig at et nytt forsøk med samme forespørsel løser problemet. Eksempler er ugyldig signatur, manglende nødvendig autentisering, en ikke-støttet form på nyttelasten eller en forespørsel som bryter en permanent valideringsregel. Før du velger 4xx, bør du kontrollere om avsenderen behandler statusen som en permanent feil. Enkelte plattformer har egne regler for mislykkede leveringer.
Bruk 429 med forsiktighet. HTTP definerer 429 for hastighetsbegrensning, og headeren Retry-After kan angi når et nytt forsøk kan være passende. Ikke alle webhook-avsendere tolker imidlertid 429 på samme måte. Hvis køen er full eller tjenesten er overbelastet, må du bekrefte at leverandøren vil prøve på nytt på en trygg måte, og at tidsplanen for nye forsøk ikke vil forverre overbelastningen. En inntakskø med avgrensning og en plan for tilbakepress er vanligvis bedre enn å la forespørsler mislykkes uforutsigbart.
Returner 5xx når mottakeren ikke trygt kan godta hendelsen på grunn av et midlertidig problem. Dette omfatter en utilgjengelig database, en mislykket skriving til en varig kø eller en intern feil som hindret validering eller lagring. Å returnere 200 mens hendelsen forkastes i stillhet gjør gjenoppretting vanskeligere fordi avsenderen ikke har noen grunn til å prøve igjen.
Unngå å basere webhook-levering på omdirigeringer som 301, 302 eller 307. Håndtering av omdirigeringer varierer mellom klienter, og omdirigering av en signert forespørsel kan skape uklarhet rundt mål, metode og innhold. Konfigurer leverandøren med det endelige HTTPS-endepunktet i stedet.
En pålitelig svarpolicy for sporingshendelser
For de fleste integrasjoner av sporings-webhooks er følgende policy et fornuftig utgangspunkt:
- Returner
200eller202etter at hendelsen har bestått autentisering og er lagret varig eller lagt i en pålitelig kø. - Returner et 4xx-svar for ugyldig signatur, ugyldig autentisering eller en permanent ubrukelig nyttelast, i tråd med leverandørens dokumenterte regler.
- Returner 5xx når en midlertidig feil hindrer varig godkjenning.
- Returner et vellykket svar for en trygt gjenkjent duplikat, samtidig som du hindrer dupliserte forretningseffekter.
- Hold behandleren rask og mål svartiden for bekreftelsen.
- Test scenarier med tidsavbrudd, nye forsøk, duplikater, feil rekkefølge, feilformatert innhold og leverandørutfall før produksjonssetting.
Hvis du integrerer et sporings-API, bør du starte med leverandørens webhook-dokumentasjon og bekrefte godkjente suksesskoder, metoden for signering av forespørsler, tidsavbrudd, utløsere for nye forsøk, skjemastruktur for nyttelasten og hendelses-ID. For 17TRACK-integrasjoner er den offisielle dokumentasjonen for Tracking API riktig sted å kontrollere den leverandørspesifikke avtalen, i stedet for å utlede den fra generell HTTP-praksis.
Sjekkliste for implementering
- Endepunktet er tilgjengelig over HTTPS og har en stabil produksjons-URL.
- Autentisering og signaturverifisering skjer før forretningsbehandling.
- Den rå forespørselen eller en verifiserbar representasjon beholdes der det kreves for signaturkontroller og feilsøking.
- Hendelsen lagres før suksessvaret sendes.
- Dupliserte leveringer er trygge og gjentar ikke irreversible handlinger.
- Arbeidere kan prøve intern behandling på nytt uavhengig av avsenderens HTTP-syklus for nye forsøk.
- Logger inneholder hendelses-ID, leveringstid, svarkode, behandlingstilstand og korrelasjons-ID uten å eksponere hemmeligheter.
- Varsler skiller mellom tidsavbrudd for endepunktet, 4xx-valideringsfeil, 5xx-utfall, køforsinkelser og dupliserte leveringer.
- Den dokumenterte leverandøratferden er testet med reelle hendelser eller sandkassehendelser.
Vanlige spørsmål
Er 200 OK bedre enn 202 Accepted for en webhook?
Ingen av dem er universelt bedre. Bruk 200 OK når forespørselen er godtatt og integrasjonen behandler svaret som en generell suksess. Bruk 202 Accepted når hendelsen er godtatt for asynkron behandling. Bekreft at avsenderen klassifiserer det valgte 2xx-svaret som vellykket.
Bør et webhook-endepunkt vente til sporingsoppdateringen er ferdig behandlet?
Vanligvis ikke. Det bør bare vente til hendelsen er autentisert, validert og varig godtatt. Langvarig arbeid bør normalt skje etter bekreftelsen, slik at en langsom avhengighet ikke forårsaker et unngåelig tidsavbrudd og nytt forsøk.
Hva bør skje når den samme sporingshendelsen kommer to ganger?
Gjenkjenn den ved hjelp av leverandørens hendelses-ID eller en nøye utformet tilsvarende nøkkel, hopp over dupliserte sideeffekter og returner et suksessvar hvis hendelsen allerede er godtatt. Dette gjør nye forsøk trygge uten å skjule nye behandlingsfeil.
Bør en ugyldig signatur returnere 400 eller 401?
Valget avhenger av autentiseringsmodellen din og leverandørens dokumenterte forventninger. Begge kan kommunisere avvisning, men konsekvent bruk er viktigere enn å velge én universell kode. Ikke bekreft en hendelse hvis ektheten ikke kan verifiseres.
Forårsaker et 5xx-svar alltid et nytt forsøk?
Nei. Mange webhook-systemer prøver på nytt ved tidsavbrudd og serverfeil, men utløsere og tidsplaner for nye forsøk er leverandørspesifikke. Behandle nye forsøk som en dokumentert integrasjonsatferd og verifiser dem i et testmiljø.
Kilder
- RFC 9110: HTTP Semantics — definisjoner for vellykkede svar, klientfeil, serverfeil, omdirigering og svarhåndtering.
- RFC 6585: Additional HTTP Status Codes — spesifikasjon for
429 Too Many Requests. - Stripe Webhooks Documentation — praktisk veiledning om webhook-svar, asynkron behandling og håndtering av dupliserte hendelser.
- GitHub Docs: Handling Webhook Deliveries — inspeksjon av leveringer og driftsmessige hensyn for webhook-integrasjoner.
- 17TRACK Tracking API Documentation — leverandørspesifikk dokumentasjon som bør kontrolleres ved implementering av integrasjoner med sporings-API.


