Skip to main content
AcasăBlogGhiduriCe ar trebui să returneze un endpoint de webhook pentru urmărire? Coduri de stare, expirări și reîncercări?

Ce ar trebui să returneze un endpoint de webhook pentru urmărire? Coduri de stare, expirări și reîncercări?

17TRACK

Un endpoint webhook de urmărire ar trebui să returneze un răspuns 2xx rapid și intenționat după ce a acceptat evenimentul pentru procesare. În majoritatea integrărilor, cea mai sigură abordare este să autentificați cererea, să validați payload-ul, să stocați sau să puneți evenimentul într-o coadă și să confirmați primirea acestuia cu 200 OK sau 202 Accepted. Folosiți răspunsuri 4xx pentru cererile pe care expeditorul nu ar trebui să le retrimită și răspunsuri 5xx atunci când o problemă temporară pe partea serverului a împiedicat acceptarea. Comportamentul exact privind timeout-ul și reîncercările depinde în continuare de contractul furnizorului webhook-ului, astfel încât implementarea ar trebui concepută pe baza comportamentului documentat al expeditorului, nu a presupunerilor.

Ce coduri de stare și timeout-uri ar trebui să returneze un endpoint webhook de urmărire

Pentru un webhook de urmărire sau de stare a livrării, această distincție este importantă deoarece evenimentele de livrare pot ajunge de mai multe ori, pot ajunge în ordine greșită sau pot fi retransmise după o defecțiune de rețea. Rolul endpoint-ului nu este neapărat să finalizeze fiecare operațiune de business înainte de a răspunde. Primul său rol este să ia o decizie fiabilă cu privire la acceptarea evenimentului.

Contractul răspunsului în termeni practici

Un răspuns webhook are două categorii de destinatari: sistemul expeditor și propria aplicație. Expeditorul are nevoie de un rezultat HTTP clar pentru a decide dacă marchează livrarea ca reușită, o reîncearcă sau o oprește. Aplicația dumneavoastră are nevoie de suficient timp pentru a verifica și înregistra durabil evenimentul. Aceste obiective sunt mai ușor de atins atunci când endpoint-ul are o cale sincronă scurtă și o cale separată de procesare asincronă.

  1. Primiți cererea HTTP prin HTTPS.
  2. Verificați semnătura, datele de autentificare, marca temporală sau alte controale de integritate a cererii solicitate de furnizor.
  3. Analizați și validați payload-ul fără a efectua operațiuni lente în sisteme downstream.
  4. Scrieți evenimentul sau o înregistrare de deduplicare și referința evenimentului într-o stocare durabilă sau într-o coadă fiabilă.
  5. Returnați un răspuns 2xx intenționat.
  6. Procesați asincron actualizarea urmăririi, notificarea clientului, modificarea inventarului sau orice altă acțiune de business.

Un răspuns nu ar trebui să pretindă acceptarea dacă evenimentul există doar în memoria procesului. Dacă aplicația se blochează imediat după returnarea succesului, un eveniment care nu a fost persistent poate fi pierdut, în timp ce expeditorul consideră că livrarea a reușit. Prin urmare, momentul în care returnați 2xx trebuie să corespundă garanției reale de durabilitate.

Ce cod de stare ar trebui să returneze un webhook?

RăspunsSemnificație pentru expeditorUtilizare tipică pentru webhook
200 OKCererea a fost acceptată și gestionată cu succes.Valoare implicită practică după validare și acceptare durabilă.
202 AcceptedCererea a fost acceptată pentru procesare, dar activitatea poate continua.Util atunci când evenimentul a fost pus în siguranță într-o coadă, dar procesarea de business este asincronă.
204 No ContentCererea a reușit și nu este necesar un corp al răspunsului.Potrivit atunci când furnizorul acceptă un răspuns de succes gol.
400–499Cererea este invalidă, neautorizată sau inacceptabilă în forma trimisă.Payload malformat, autentificare eșuată, semnătură invalidă sau eveniment respins permanent.
429 Too Many RequestsDestinatarul aplică limitarea ratei.Folosiți doar atunci când comportamentul de reîncercare al expeditorului și politica dumneavoastră de limitare a ratei sunt compatibile.
500–599Destinatarul nu a putut accepta cererea din cauza unei probleme de server sau temporare.Indisponibilitatea bazei de date, eșecul cozii, eșecul unei dependențe sau o eroare neașteptată a aplicației.

200 OK este adesea alegerea cea mai previzibilă, deoarece este înțeles pe scară largă ca primire reușită. 202 Accepted este, de asemenea, util semantic atunci când endpoint-ul a acceptat evenimentul pentru procesare ulterioară. Niciunul dintre coduri nu este automat corect: documentația expeditorului poate defini care răspunsuri 2xx sunt considerate reușite, iar unii furnizori pot solicita un anumit corp sau tip de conținut.

Nu returnați un răspuns 2xx doar pentru că cererea HTTP a ajuns la serverul dumneavoastră. Dacă verificarea semnăturii eșuează sau payload-ul nu poate fi interpretat în siguranță, un răspuns 4xx este de obicei mai corect. În schimb, nu returnați 4xx pentru o indisponibilitate temporară a bazei de date dacă evenimentul ar putea reuși ulterior. Un răspuns 5xx oferă unui expeditor capabil să reîncerce șansa de a livra din nou evenimentul, deși furnizorul poate aplica propria politică.

Cum ar trebui gestionate timeout-urile?

Valorile timeout-ului pentru webhook sunt specifice furnizorului. Nu există un timeout HTTP universal folosit de toate platformele de urmărire, iar un expeditor poate înceta să aștepte înainte ca aplicația dumneavoastră să finalizeze o operațiune lentă. Tratați timeout-ul documentat al expeditorului ca pe o limită maximă, nu ca pe o țintă. În mod normal, endpoint-ul ar trebui să răspundă cu mult înainte de această limită.

Cea mai frecventă greșeală de proiectare este efectuarea tuturor operațiunilor downstream înainte de confirmarea webhook-ului. Un handler poate apela succesiv o bază de date, un sistem de gestionare a comenzilor, un serviciu de notificări și un pipeline de analiză. O singură dependență lentă poate face ca expeditorul să vadă un timeout, chiar dacă aplicația dumneavoastră finalizează în cele din urmă operațiunea. Expeditorul poate reîncerca atunci, generând procesări duplicate sau actualizări concurente.

Limitați calea sincronă la activitatea necesară pentru a lua o decizie sigură de acceptare. Aceasta include de obicei autentificarea cererii, validarea de bază a schemei, stocarea durabilă a evenimentului și publicarea în coadă. Plasați îmbogățirea costisitoare, căutările la transportatori, mesajele către clienți și apelurile către API-uri terțe în spatele unui worker. Monitorizați separat timpul petrecut pentru primirea, validarea, persistența și confirmarea evenimentului față de timpul petrecut pentru procesarea acestuia.

Un timeout nu este același lucru cu o operațiune de business eșuată. Din perspectiva expeditorului, un timeout înseamnă de obicei că nu a primit un răspuns de succes utilizabil. Serviciul dumneavoastră poate să fi stocat cu succes evenimentul chiar înainte de închiderea conexiunii. De aceea, idempotența și deduplicarea sunt necesare chiar și atunci când endpoint-ul pare fiabil.

Ce cauzează reîncercările?

Un expeditor de webhook poate reîncerca după o eroare de conexiune, un timeout sau un răspuns pe care contractul său îl clasifică drept nereușit. Programul exact, numărul maxim de încercări, algoritmul de backoff și fereastra de livrare variază în funcție de furnizor. Nu promiteți un număr fix de reîncercări decât dacă acesta este menționat în documentația furnizorului.

Destinatarul ar trebui să presupună că reîncercările pot apărea și să proiecteze în mod deliberat pentru acestea:

  • Folosiți un identificator de eveniment atunci când este disponibil. Stocați-l cu o constrângere unică sau cu o cheie de deduplicare echivalentă.
  • Faceți procesarea idempotentă. Aplicarea de două ori a aceleiași actualizări privind starea livrării nu ar trebui să trimită două mesaje clienților, să creeze două rambursări sau să avanseze incorect o comandă.
  • Păstrați payload-ul original sau o înregistrare utilă de audit. Aceasta permite retransmiterea, investigarea și reconcilierea.
  • Separați acceptarea de procesare. Un worker poate reîncerca erorile interne fără a obliga expeditorul să repete întregul schimb HTTP.
  • Înregistrați codurile de răspuns și latența. O creștere a răspunsurilor 5xx, a timeout-urilor sau a ID-urilor de evenimente duplicate poate dezvălui o întrerupere înainte ca utilizatorii să raporteze actualizări de urmărire lipsă.

Un eveniment duplicat ar trebui de obicei să primească un răspuns de succes dacă evenimentul original a fost deja acceptat durabil. Returnarea unei erori pentru fiecare duplicat poate declanșa reîncercări inutile. Endpoint-ul poate înregistra faptul că evenimentul a fost văzut anterior, poate omite acțiunea de business repetată și poate returna aceeași clasă de succes utilizată pentru un eveniment nou acceptat.

Când ar trebui să returnați 4xx, 429 sau 5xx?

Returnați 4xx atunci când reîncercarea aceleiași cereri este puțin probabil să rezolve problema. Exemplele includ o semnătură invalidă, lipsa autentificării obligatorii, o structură de payload nesuportată sau o cerere care încalcă o regulă permanentă de validare. Înainte de a alege 4xx, verificați dacă expeditorul tratează acest statut ca pe un eșec permanent. Unele platforme au propriile reguli pentru livrările eșuate.

Folosiți 429 cu atenție. HTTP definește 429 pentru limitarea ratei, iar antetul Retry-After poate comunica momentul în care o reîncercare ar putea fi potrivită. Totuși, nu orice expeditor de webhook interpretează 429 în același mod. Dacă coada este plină sau serviciul este supraîncărcat, confirmați că furnizorul va reîncerca în siguranță și că programul său de reîncercare nu va agrava supraîncărcarea. O coadă de preluare limitată și un plan de backpressure sunt de obicei mai bune decât permiterea eșuării imprevizibile a cererilor.

Returnați 5xx atunci când destinatarul nu poate accepta în siguranță evenimentul din cauza unei probleme temporare. Aceasta include o bază de date indisponibilă, o scriere eșuată în coada durabilă sau o eroare internă care a împiedicat validarea ori persistența. Returnarea codului 200 în timp ce evenimentul este eliminat în tăcere îngreunează recuperarea, deoarece expeditorul nu are niciun motiv să încerce din nou.

Evitați să vă bazați pe redirecționări precum 301, 302 sau 307 pentru livrarea webhook-urilor. Gestionarea redirecționărilor diferă între clienți, iar redirecționarea unei cereri semnate poate crea ambiguități privind destinația, metoda și corpul. Configurați furnizorul cu endpoint-ul HTTPS final.

O politică fiabilă de răspuns pentru evenimentele de urmărire

Pentru majoritatea integrărilor cu webhook-uri de urmărire, următoarea politică reprezintă un punct de pornire rezonabil:

  1. Returnați 200 sau 202 după ce evenimentul a trecut de autentificare și a fost stocat durabil sau plasat într-o coadă fiabilă.
  2. Returnați un răspuns 4xx pentru o semnătură invalidă, autentificare invalidă sau un payload inutilizabil permanent, respectând regulile documentate ale furnizorului.
  3. Returnați 5xx atunci când un eșec temporar împiedică acceptarea durabilă.
  4. Returnați un răspuns de succes pentru un duplicat recunoscut în siguranță, prevenind în același timp efectele de business duplicate.
  5. Păstrați handler-ul rapid și măsurați latența confirmării.
  6. Testați scenariile de timeout, reîncercare, duplicare, ordine greșită, payload malformat și indisponibilitate a furnizorului înainte de lansarea în producție.

Dacă integrați un API de urmărire, începeți cu documentația webhook-ului furnizorului și confirmați codurile de succes acceptate, metoda de semnare a cererii, timeout-ul, declanșatorii reîncercărilor, schema payload-ului și identificatorul evenimentului. Pentru integrările 17TRACK, documentația oficială Tracking API este locul potrivit pentru a verifica contractul specific furnizorului, în loc să îl deduceți din practica HTTP generală.

Listă de verificare pentru implementare

  • Endpoint-ul este accesibil prin HTTPS și are un URL de producție stabil.
  • Autentificarea și verificarea semnăturii au loc înaintea procesării de business.
  • Cererea brută sau o reprezentare verificabilă este păstrată atunci când este necesar pentru verificarea semnăturii și depanare.
  • Evenimentul este persistent înainte de trimiterea răspunsului de succes.
  • Livrările duplicate sunt sigure și nu repetă acțiuni ireversibile.
  • Worker-ele pot reîncerca procesarea internă independent de ciclul de reîncercare HTTP al expeditorului.
  • Jurnalele includ ID-ul evenimentului, ora livrării, codul răspunsului, starea procesării și ID-ul de corelare, fără a expune secrete.
  • Alertele disting între timeout-urile endpoint-ului, erorile de validare 4xx, întreruperile 5xx, întârzierile cozii și livrările duplicate.
  • Comportamentul documentat al furnizorului a fost testat cu evenimente reale sau sandbox.

Întrebări frecvente

Este 200 OK mai bun decât 202 Accepted pentru un webhook?

Niciunul nu este universal mai bun. Folosiți 200 OK atunci când cererea a fost acceptată și integrarea dumneavoastră tratează răspunsul ca pe un succes general. Folosiți 202 Accepted atunci când evenimentul a fost acceptat pentru procesare asincronă. Confirmați că expeditorul clasifică răspunsul 2xx ales drept succes.

Ar trebui ca un endpoint webhook să aștepte până când actualizarea urmăririi este procesată complet?

De obicei, nu. Ar trebui să aștepte doar până când evenimentul este autentificat, validat și acceptat durabil. Activitățile de durată ar trebui să aibă loc în mod normal după confirmare, astfel încât o dependență lentă să nu provoace un timeout și o reîncercare evitabile.

Ce ar trebui să se întâmple când același eveniment de urmărire ajunge de două ori?

Recunoașteți-l folosind ID-ul evenimentului furnizorului sau o cheie echivalentă proiectată cu atenție, omiteți efectele secundare duplicate și returnați un răspuns de succes dacă evenimentul a fost deja acceptat. Astfel, reîncercările devin sigure fără a ascunde erorile noi de procesare.

Ar trebui ca o semnătură invalidă să returneze 400 sau 401?

Alegerea depinde de modelul dumneavoastră de autentificare și de așteptările documentate ale furnizorului. Ambele pot comunica respingerea, dar consecvența contează mai mult decât alegerea uneia în mod universal. Nu confirmați un eveniment a cărui autenticitate nu o puteți verifica.

Un răspuns 5xx cauzează întotdeauna o reîncercare?

Nu. Multe sisteme webhook reîncearcă după timeout-uri și erori de server, dar declanșatorii și programele de reîncercare sunt specifice furnizorului. Tratați reîncercările ca pe un comportament documentat al integrării și verificați-le într-un mediu de testare.

Surse