Skip to main content
KezdőlapBlogÚtmutatókMit kell visszaadnia egy követési webhook-végpontnak? Állapotkódok, időkorlátok és újrapróbálkozások?

Mit kell visszaadnia egy követési webhook-végpontnak? Állapotkódok, időkorlátok és újrapróbálkozások?

17TRACK

Egy nyomkövetési webhook-végpontnak gyors, szándékos 2xx választ kell visszaadnia, miután elfogadta az eseményt feldolgozásra. A legtöbb integrációban a legbiztonságosabb minta a kérés hitelesítése, a hasznos adatok ellenőrzése, az esemény tárolása vagy sorba állítása, majd a nyugtázása 200 OK vagy 202 Accepted válasszal. A 4xx válaszokat olyan kérésekhez használja, amelyeket a küldőnek nem kell újrapróbálnia, az 5xx válaszokat pedig akkor, ha egy ideiglenes szerveroldali probléma megakadályozta az elfogadást. A pontos időkorlát- és újrapróbálkozási viselkedés továbbra is a webhook-szolgáltató szerződésétől függ, ezért a megvalósítást a dokumentált küldői viselkedésre, ne pedig feltételezésekre alapozza.

Milyen állapotkódokat és időkorlátokat adjon vissza egy nyomkövetési webhook-végpont

Egy nyomkövetési vagy szállításiállapot-webhook esetében ez a különbségtétel azért fontos, mert a kézbesítési események többször is megérkezhetnek, sorrenden kívül érkezhetnek, vagy hálózati hiba után újra lejátszhatók. A végpont feladata nem feltétlenül az, hogy minden üzleti műveletet befejezzen a válaszadás előtt. Elsődleges feladata annak megbízható eldöntése, hogy az eseményt elfogadta-e.

A válaszszerződés gyakorlati jelentése

Egy webhook-válasznak két közönsége van: a küldő rendszer és a saját alkalmazása. A küldőnek egyértelmű HTTP-eredményre van szüksége annak eldöntéséhez, hogy sikeresnek jelölje-e a kézbesítést, újrapróbálja-e, vagy leálljon. Az alkalmazásának elegendő időre van szüksége az esemény ellenőrzéséhez és tartós rögzítéséhez. Ezek a célok könnyebben teljesíthetők, ha a végpontnak van egy rövid szinkron és egy külön aszinkron feldolgozási útvonala.

  1. Fogadja a HTTP-kérést HTTPS-en keresztül.
  2. Ellenőrizze a szolgáltató által megkövetelt aláírást, hitelesítési adatokat, időbélyeget vagy más kérésintegritási vezérlőket.
  3. Értelmezze és ellenőrizze a hasznos adatokat lassú háttérműveletek végrehajtása nélkül.
  4. Írja az eseményt, illetve a deduplikációs rekordot és az eseményhivatkozást tartós tárhelyre vagy megbízható várólistára.
  5. Adjon vissza szándékos 2xx választ.
  6. A nyomkövetési frissítést, ügyfélértesítést, készletváltozást vagy más üzleti műveletet aszinkron módon dolgozza fel.

A válasznak nem szabad elfogadást jeleznie, ha az esemény csak a folyamat memóriájában létezik. Ha az alkalmazás közvetlenül a sikeres válasz visszaadása után összeomlik, a soha nem perzisztált esemény elveszhet, miközben a küldő úgy véli, hogy a kézbesítés sikeres volt. Ezért a 2xx válasz visszaadásának időpontjának meg kell egyeznie a tényleges tartóssági garanciával.

Milyen állapotkódot adjon vissza egy webhook?

VálaszJelentése a küldő számáraTipikus webhook-használat
200 OKA kérést elfogadtuk és sikeresen kezeltük.Gyakorlati alapértelmezés az ellenőrzés és a tartós elfogadás után.
202 AcceptedA kérést feldolgozásra elfogadtuk, de a munka folytatódhat.Hasznos, ha az eseményt biztonságosan sorba állítottuk, de az üzleti feldolgozás aszinkron.
204 No ContentA kérés sikeres volt, és nincs szükség válasz törzsére.Megfelelő, ha a szolgáltató elfogadja az üres sikeres választ.
400–499A kérés érvénytelen, nem hitelesített vagy az adott formában nem elfogadható.Hibás hasznos adatok, sikertelen hitelesítés, érvénytelen aláírás vagy véglegesen elutasított esemény.
429 Too Many RequestsA fogadó sebességkorlátozást alkalmaz.Csak akkor használja, ha a küldő újrapróbálkozási viselkedése és a sebességkorlátozási szabályzata kompatibilis.
500–599A fogadó szerveroldali vagy ideiglenes probléma miatt nem tudta elfogadni a kérést.Adatbázis-kiesés, várólista-hiba, függőségi hiba vagy váratlan alkalmazáshiba.

A 200 OK gyakran a legkevésbé meglepő választás, mert széles körben sikeres fogadásként értelmezik. A 202 Accepted akkor is szemantikailag hasznos, ha a végpont elfogadta az eseményt későbbi feldolgozásra. Egyik kód sem automatikusan helyes: a küldő dokumentációja meghatározhatja, hogy mely 2xx válaszok számítanak sikeresnek, és egyes szolgáltatók meghatározott törzset vagy tartalomtípust várhatnak.

Ne adjon vissza 2xx választ pusztán azért, mert a HTTP-kérés elérte a szerverét. Ha az aláírás ellenőrzése sikertelen, vagy a hasznos adatok nem értelmezhetők biztonságosan, általában egy 4xx válasz az őszintébb. Ezzel szemben ne adjon vissza 4xx választ ideiglenes adatbázis-kiesés miatt, ha az esemény később sikeresen feldolgozható. Az 5xx válasz lehetőséget ad az újrapróbálkozásra képes küldőnek az esemény újbóli kézbesítésére, bár a szolgáltató saját szabályzatot alkalmazhat.

Hogyan kezelje az időkorlátokat?

A webhook időkorlátjai szolgáltatónként eltérnek. Nincs olyan univerzális HTTP-időkorlát, amelyet minden nyomkövetési platform használ, és előfordulhat, hogy a küldő már azelőtt abbahagyja a várakozást, hogy az alkalmazása befejezné a lassú műveletet. A küldő dokumentált időkorlátját maximális határként, ne célértékként kezelje. A végpontnak általában jóval e határ előtt kell válaszolnia.

A leggyakoribb tervezési hiba, hogy minden háttérmunkát a webhook nyugtázása előtt végeznek el. A kezelő egymás után hívhat adatbázist, rendeléskezelő rendszert, értesítési szolgáltatást és elemzési folyamatot. Egyetlen lassú függőség miatt a küldő időtúllépést láthat, még akkor is, ha az alkalmazás végül befejezi a munkát. A küldő ezután újrapróbálkozhat, ami ismételt feldolgozást vagy egymással versengő frissítéseket eredményezhet.

A szinkron útvonalat korlátozza a biztonságos elfogadási döntéshez szükséges munkára. Ez általában magában foglalja a kérés hitelesítését, az alapvető sémaellenőrzést, az esemény tartós tárolását és a várólistára helyezést. A költséges bővítést, fuvarozói lekérdezéseket, ügyfélkommunikációt és harmadik féltől származó API-hívásokat bízza workerre. A fogadásra, ellenőrzésre, perzisztálásra és nyugtázásra fordított időt külön figyelje a feldolgozásra fordított időtől.

Az időtúllépés nem azonos a sikertelen üzleti művelettel. A küldő szemszögéből az időtúllépés általában azt jelenti, hogy nem kapott használható sikeres választ. Előfordulhat, hogy a szolgáltatása közvetlenül a kapcsolat lezárása előtt sikeresen tárolta az eseményt. Ezért az idempotencia és a deduplikáció akkor is szükséges, ha a végpont megbízhatónak tűnik.

Mi okozza az újrapróbálkozásokat?

A webhook küldője újrapróbálkozhat kapcsolati hiba, időtúllépés vagy olyan válasz után, amelyet a szerződése sikertelennek minősít. A pontos ütemezés, a maximális kísérletszám, a visszalépési algoritmus és a kézbesítési időablak szolgáltatónként eltér. Ne ígérjen rögzített számú újrapróbálkozást, hacsak azt a szolgáltató dokumentációja nem rögzíti.

A fogadónak feltételeznie kell, hogy újrapróbálkozások történhetnek, és tudatosan kell ezekre terveznie:

  • Használjon eseményazonosítót, ha rendelkezésre áll. Tárolja egyedi megszorítással vagy ezzel egyenértékű deduplikációs kulccsal.
  • Tegye idempotenssé a feldolgozást. Ugyanazon kézbesítésiállapot-frissítés kétszeri alkalmazása ne küldjön két ügyfélüzenetet, ne hozzon létre két visszatérítést, és ne léptessen helytelenül előre egy rendelést.
  • Őrizze meg az eredeti hasznos adatokat vagy egy hasznos auditrekordot. Ez támogatja az újrajátszást, a kivizsgálást és az egyeztetést.
  • Válassza külön az elfogadást és a feldolgozást. Egy worker újrapróbálhatja a belső hibákat anélkül, hogy a küldőt a teljes HTTP-kommunikáció megismétlésére kényszerítené.
  • Rögzítse a válaszkódokat és a késleltetést. Az 5xx válaszok, időtúllépések vagy ismétlődő eseményazonosítók számának növekedése jelezheti a kiesést, mielőtt a felhasználók jelentenék a hiányzó nyomkövetési frissítéseket.

A duplikált eseménynek általában sikeres választ kell kapnia, ha az eredeti eseményt már tartósan elfogadták. Minden duplikátum hibával való visszautasítása szükségtelen újrapróbálkozásokat indíthat el. A végpont rögzítheti, hogy az eseményt már látta, kihagyhatja az ismételt üzleti műveletet, és ugyanazt a sikerosztályt adhatja vissza, mint egy újonnan elfogadott eseménynél.

Mikor adjon vissza 4xx, 429 vagy 5xx választ?

Adjon vissza 4xx választ, ha ugyanazon kérés újrapróbálása várhatóan nem oldja meg a problémát. Ilyen például az érvénytelen aláírás, a szükséges hitelesítés hiánya, a nem támogatott adatforma vagy a tartós ellenőrzési szabályt megsértő kérés. A 4xx kiválasztása előtt ellenőrizze, hogy a küldő végleges hibaként kezeli-e ezt az állapotot. Egyes platformok saját szabályokkal rendelkeznek a sikertelen kézbesítésekre.

A 429-et körültekintően használja. A HTTP a 429-et sebességkorlátozásra definiálja, a Retry-After fejléc pedig jelezheti, mikor lehet megfelelő az újrapróbálás. Nem minden webhook-küldő értelmezi azonban ugyanúgy a 429-et. Ha a várólista megtelt vagy a szolgáltatás túlterhelt, győződjön meg arról, hogy a szolgáltató biztonságosan újrapróbálkozik, és az ütemezése nem súlyosbítja a túlterhelést. A korlátozott befogadási várólista és a visszanyomási terv általában jobb, mint ha a kérések kiszámíthatatlanul meghiúsulnának.

Adjon vissza 5xx választ, ha a fogadó ideiglenes probléma miatt nem tudja biztonságosan elfogadni az eseményt. Ide tartozik az elérhetetlen adatbázis, a tartós várólistára írás sikertelensége vagy az ellenőrzést, illetve perzisztálást megakadályozó belső hiba. Ha 200-at ad vissza az esemény csendes eldobása mellett, a helyreállítás nehezebbé válik, mert a küldőnek nem lesz oka újrapróbálkozni.

Kerülje az olyan átirányításokra való támaszkodást, mint a 301, 302 vagy 307 webhook-kézbesítésnél. Az átirányítások kezelése kliensenként eltér, és egy aláírt kérés átirányítása bizonytalanságot okozhat a cél, a metódus és a törzs tekintetében. Ehelyett a szolgáltatót a végleges HTTPS-végponttal állítsa be.

Megbízható válaszszabályzat nyomkövetési eseményekhez

A legtöbb nyomkövetési webhook-integráció esetében a következő szabályzat ésszerű kiindulópont:

  1. Adjon vissza 200 vagy 202 választ, miután az esemény átment a hitelesítésen, és tartósan tárolta vagy megbízható várólistára helyezte.
  2. Adjon vissza 4xx választ érvénytelen aláírás, érvénytelen hitelesítés vagy véglegesen használhatatlan hasznos adatok esetén, a szolgáltató dokumentált szabályait követve.
  3. Adjon vissza 5xx választ, ha ideiglenes hiba megakadályozza a tartós elfogadást.
  4. Biztonságosan felismert duplikátum esetén adjon vissza sikeres választ, miközben megakadályozza a duplikált üzleti hatásokat.
  5. Tartsa gyorsan a kezelőt, és mérje a nyugtázás késleltetését.
  6. Éles indítás előtt tesztelje az időtúllépési, újrapróbálási, duplikációs, sorrenden kívüli, hibás és szolgáltatói kiesési helyzeteket.

Ha nyomkövetési API-t integrál, kezdje a szolgáltató webhook-dokumentációjával, és erősítse meg az elfogadott sikeres kódokat, a kérésaláírás módját, az időkorlátot, az újrapróbálás kiváltó okait, a hasznos adatok sémáját és az eseményazonosítót. A 17TRACK-integrációk esetében a hivatalos Tracking API dokumentáció a megfelelő hely a szolgáltatóspecifikus szerződés ellenőrzésére, nem pedig az általános HTTP-gyakorlatból való következtetés.

Megvalósítási ellenőrzőlista

  • A végpont HTTPS-en keresztül elérhető, és stabil éles URL-lel rendelkezik.
  • A hitelesítés és az aláírás ellenőrzése az üzleti feldolgozás előtt történik.
  • A nyers kérést vagy annak ellenőrizhető reprezentációját megőrzi, ahol ez szükséges az aláírás-ellenőrzéshez és a hibaelhárításhoz.
  • Az esemény perzisztálása a sikeres válasz elküldése előtt megtörténik.
  • A duplikált kézbesítések biztonságosak, és nem ismételnek meg visszafordíthatatlan műveleteket.
  • A workerek a küldő HTTP-újrapróbálási ciklusától függetlenül újrapróbálhatják a belső feldolgozást.
  • A naplók tartalmazzák az eseményazonosítót, a kézbesítés idejét, a válaszkódot, a feldolgozási állapotot és a korrelációs azonosítót, titkok felfedése nélkül.
  • A riasztások megkülönböztetik a végpont időtúllépéseit, a 4xx ellenőrzési hibákat, az 5xx kieséseket, a várólisták késéseit és a duplikált kézbesítéseket.
  • A dokumentált szolgáltatói viselkedést valódi vagy sandbox-eseményekkel tesztelték.

GYIK

A 200 OK jobb a 202 Acceptednél webhook esetén?

Egyik sem univerzálisan jobb. Használjon 200 OK választ, ha a kérést elfogadta, és az integráció általános sikeres válaszként kezeli. Használjon 202 Accepted választ, ha az eseményt aszinkron feldolgozásra fogadta el. Erősítse meg, hogy a küldő sikeresnek minősíti-e a választott 2xx választ.

Meg kell várnia a webhook-végpontnak, amíg a nyomkövetési frissítés teljesen feldolgozásra kerül?

Általában nem. Csak addig kell várnia, amíg az eseményt hitelesítik, ellenőrzik és tartósan elfogadják. A hosszú műveleteknek általában a nyugtázás után kell megtörténniük, hogy egy lassú függőség ne okozzon elkerülhető időtúllépést és újrapróbálkozást.

Mi történjen, ha ugyanaz a nyomkövetési esemény kétszer érkezik meg?

Ismerje fel a szolgáltató eseményazonosítója vagy egy gondosan kialakított egyenértékű kulcs alapján, hagyja ki a duplikált mellékhatásokat, és adjon vissza sikeres választ, ha az eseményt már elfogadták. Ez biztonságossá teszi az újrapróbálkozásokat anélkül, hogy elrejtené az új feldolgozási hibákat.

400 vagy 401 választ adjon vissza érvénytelen aláírás esetén?

A választás a hitelesítési modelltől és a szolgáltató dokumentált elvárásaitól függ. Mindkettő elutasítást jelezhet, de a következetesség fontosabb, mint az egyik univerzális kiválasztása. Ne nyugtázzon olyan eseményt, amelynek hitelességét nem tudja ellenőrizni.

Az 5xx válasz mindig újrapróbálkozást okoz?

Nem. Számos webhook-rendszer újrapróbálja az időtúllépéseket és a szerverhibákat, de a kiváltó okok és az ütemezések szolgáltatónként eltérnek. Az újrapróbálkozásokat dokumentált integrációs viselkedésként kezelje, és ellenőrizze tesztkörnyezetben.

Források