Skip to main content
Faqja kryesoreBlogUdhëzuesÇfarë duhet të kthejë një endpoint webhook-u për gjurmimin? Kodet e statusit, afatet kohore dhe riprovimet?

Çfarë duhet të kthejë një endpoint webhook-u për gjurmimin? Kodet e statusit, afatet kohore dhe riprovimet?

17TRACK

Një endpoint webhook për gjurmimin duhet të kthejë një përgjigje të shpejtë dhe të qëllimshme 2xx pasi të ketë pranuar ngjarjen për përpunim. Në shumicën e integrimeve, modeli më i sigurt është të autentikoni kërkesën, të validoni payload-in, të ruani ose vendosni në radhë ngjarjen dhe ta konfirmoni me 200 OK ose 202 Accepted. Përdorni përgjigje 4xx për kërkesat që dërguesi nuk duhet t’i provojë përsëri dhe përgjigje 5xx kur një problem i përkohshëm në anën e serverit pengoi pranimin. Sjellja e saktë e afatit kohor dhe riprovimit varet ende nga kontrata e ofruesit të webhook-ut, prandaj implementimi juaj duhet të bazohet në sjelljen e dokumentuar të dërguesit dhe jo në supozime.

Çfarë duhet të kthejë një endpoint webhook për gjurmimin: kodet e statusit dhe afatet kohore

Për një webhook të statusit të gjurmimit ose dërgesës, ky dallim ka rëndësi sepse ngjarjet e dorëzimit mund të mbërrijnë më shumë se një herë, jashtë rendit ose të riluajhen pas një dështimi të rrjetit. Detyra e endpoint-it nuk është domosdoshmërisht të përfundojë çdo operacion biznesi përpara se të përgjigjet. Detyra e tij e parë është të marrë një vendim të besueshëm nëse ngjarja është pranuar.

Kontrata e përgjigjes në terma praktikë

Një përgjigje webhook ka dy audienca: sistemin dërgues dhe aplikacionin tuaj. Dërguesi ka nevojë për një rezultat të qartë HTTP që të vendosë nëse dorëzimi duhet të shënohet si i suksesshëm, të provohet përsëri apo të ndalet. Aplikacioni juaj ka nevojë për kohë të mjaftueshme për ta verifikuar dhe regjistruar në mënyrë të qëndrueshme ngjarjen. Këto synime arrihen më lehtë kur endpoint-i ka një rrugë të vogël sinkrone dhe një rrugë të veçantë përpunimi asinkron.

  1. Merrni kërkesën HTTP përmes HTTPS.
  2. Kontrolloni nënshkrimin, kredencialet e autentikimit, vulën kohore ose kontrolle të tjera të integritetit të kërkesës të kërkuara nga ofruesi.
  3. Analizoni dhe validoni payload-in pa kryer punë të ngadaltë në sistemet pasuese.
  4. Shkruajeni ngjarjen, ose një regjistrim deduplikimi dhe referencën e ngjarjes, në ruajtje të qëndrueshme ose në një radhë të besueshme.
  5. Ktheni një përgjigje të qëllimshme 2xx.
  6. Përpunoni në mënyrë asinkrone përditësimin e gjurmimit, njoftimin e klientit, ndryshimin e inventarit ose veprimin tjetër të biznesit.

Një përgjigje nuk duhet të pretendojë pranimin nëse ngjarja ekziston vetëm në memorien e procesit. Nëse aplikacioni rrëzohet menjëherë pas kthimit të suksesit, një ngjarje që nuk është ruajtur kurrë mund të humbasë ndërsa dërguesi beson se dorëzimi ishte i suksesshëm. Prandaj, momenti kur ktheni 2xx duhet të përputhet me garancinë tuaj reale të qëndrueshmërisë.

Cilin kod statusi duhet të kthejë një webhook?

PërgjigjjaKuptimi për dërguesinPërdorimi tipik i webhook-ut
200 OKKërkesa u pranua dhe u trajtua me sukses.Parazgjedhje praktike pas validimit dhe pranimit të qëndrueshëm.
202 AcceptedKërkesa u pranua për përpunim, por puna mund të vazhdojë.E dobishme kur ngjarja është vendosur në mënyrë të sigurt në radhë, por përpunimi i biznesit është asinkron.
204 No ContentKërkesa pati sukses dhe nuk nevojitet trup përgjigjeje.E përshtatshme kur ofruesi pranon një përgjigje të zbrazët suksesi.
400–499Kërkesa është e pavlefshme, e paautorizuar ose e papranueshme në formën e dërguar.Payload i keqformuar, autentikim i dështuar, nënshkrim i pavlefshëm ose ngjarje e refuzuar përgjithmonë.
429 Too Many RequestsMarrësi po zbaton kufizim të normës.Përdoreni vetëm kur sjellja e riprovimit të dërguesit dhe politika juaj e kufizimit janë të pajtueshme.
500–599Marrësi nuk mund ta pranonte kërkesën për shkak të një problemi në server ose të përkohshëm.Ndërprerje e bazës së të dhënave, dështim i radhës, dështim i varësisë ose gabim i papritur i aplikacionit.

200 OK është shpesh zgjedhja më pak befasuese sepse kuptohet gjerësisht si pranim i suksesshëm. 202 Accepted është gjithashtu i dobishëm në aspektin semantik kur endpoint-i e ka pranuar ngjarjen për përpunim të mëvonshëm. Asnjë kod nuk është automatikisht i saktë: dokumentacioni i dërguesit mund të përcaktojë se cilat përgjigje 2xx llogariten si të suksesshme dhe disa ofrues mund të presin një trup ose lloj të caktuar përmbajtjeje.

Mos ktheni përgjigje 2xx vetëm sepse kërkesa HTTP arriti në serverin tuaj. Nëse verifikimi i nënshkrimit dështon ose payload-i nuk mund të interpretohet në mënyrë të sigurt, një përgjigje 4xx zakonisht është më e saktë. Në të kundërt, mos ktheni 4xx për një ndërprerje të përkohshme të bazës së të dhënave nëse ngjarja mund të ketë sukses më vonë. Një përgjigje 5xx i jep një dërguesi që mbështet riprovimin mundësinë ta dorëzojë përsëri ngjarjen, megjithëse ofruesi mund të zbatojë politikën e vet.

Si duhet të trajtohen afatet kohore?

Vlerat e afatit kohor të webhook-ut janë specifike për ofruesin. Nuk ekziston një afat universal HTTP që përdoret nga çdo platformë gjurmimi dhe dërguesi mund të ndalojë së prituri përpara se aplikacioni juaj të përfundojë një operacion të ngadaltë. Trajtojeni afatin e dokumentuar të dërguesit si kufi maksimal, jo si objektiv. Endpoint-i juaj normalisht duhet të përgjigjet shumë përpara këtij kufiri.

Gabimi më i zakonshëm i projektimit është kryerja e të gjithë punës pasuese përpara konfirmimit të webhook-ut. Një trajtues mund të thërrasë një bazë të dhënash, sistem menaxhimi porosish, shërbim njoftimesh dhe pipeline analitike me radhë. Një varësi e ngadaltë mund ta bëjë dërguesin të shohë një timeout edhe pse aplikacioni juaj përfundon punën më vonë. Dërguesi mund të provojë përsëri, duke krijuar përpunim të dyfishtë ose përditësime konkurruese.

Mbajeni rrugën sinkrone të kufizuar vetëm në punën e nevojshme për të marrë një vendim të sigurt pranimi. Kjo zakonisht përfshin autentikimin e kërkesës, validimin bazë të skemës, ruajtjen e qëndrueshme të ngjarjes dhe publikimin në radhë. Vendosni pasurimin e kushtueshëm, kërkimet te transportuesit, mesazhet për klientët dhe thirrjet API të palëve të treta pas një worker-i. Monitoroni veçmas kohën e marrjes, validimit, ruajtjes dhe konfirmimit të ngjarjes nga koha e shpenzuar për përpunimin e saj.

Një timeout nuk është i njëjtë me një operacion biznesi të dështuar. Nga këndvështrimi i dërguesit, një timeout zakonisht do të thotë se ai nuk mori një përgjigje të përdorshme suksesi. Shërbimi juaj mund ta ketë ruajtur ngjarjen me sukses pak para mbylljes së lidhjes. Për këtë arsye, idempotenca dhe deduplikimi janë të nevojshme edhe kur endpoint-i duket i besueshëm.

Çfarë shkakton riprovimet?

Një dërgues webhook mund të provojë përsëri pas një gabimi lidhjeje, timeout-i ose një përgjigjeje që kontrata e tij e klasifikon si të pasuksesshme. Orari i saktë, numri maksimal i përpjekjeve, algoritmi i backoff-it dhe dritarja e dorëzimit ndryshojnë sipas ofruesit. Mos premtoni një numër fiks riprovimesh nëse nuk përcaktohet në dokumentacionin e ofruesit.

Marrësi duhet të supozojë se riprovimet mund të ndodhin dhe të projektojë qëllimisht për to:

  • Përdorni një identifikues ngjarjeje kur është i disponueshëm. Ruajeni me një kufizim unik ose një çelës ekuivalent deduplikimi.
  • Bëjeni përpunimin idempotent. Zbatimi dy herë i të njëjtit përditësim të statusit të dorëzimit nuk duhet të dërgojë dy mesazhe klienti, të krijojë dy rimbursime ose të avancojë gabimisht një porosi.
  • Mbani payload-in origjinal ose një regjistrim të dobishëm auditimi. Kjo mbështet riluajtjen, hetimin dhe rakordimin.
  • Ndajeni pranimin nga përpunimi. Një worker mund të provojë përsëri dështimet e brendshme pa e detyruar dërguesin të përsërisë të gjithë shkëmbimin HTTP.
  • Regjistroni kodet e përgjigjes dhe vonesën. Rritja e përgjigjeve 5xx, timeout-eve ose ID-ve të dyfishta të ngjarjeve mund të zbulojë një ndërprerje përpara se përdoruesit të raportojnë mungesën e përditësimeve të gjurmimit.

Një ngjarje e dyfishtë zakonisht duhet të marrë një përgjigje të suksesshme nëse ngjarja origjinale ishte pranuar tashmë në mënyrë të qëndrueshme. Kthimi i një gabimi për çdo dublikatë mund të shkaktojë riprovime të panevojshme. Endpoint-i mund të regjistrojë se ngjarja ishte parë më parë, të anashkalojë veprimin e përsëritur të biznesit dhe të kthejë të njëjtën klasë suksesi të përdorur për një ngjarje të re të pranuar.

Kur duhet të ktheni 4xx, 429 ose 5xx?

Ktheni 4xx kur riprovimi i së njëjtës kërkesë nuk ka gjasa ta zgjidhë problemin. Shembuj janë nënshkrimi i pavlefshëm, mungesa e autentikimit të kërkuar, një formë payload-i e pambështetur ose një kërkesë që shkel një rregull të përhershëm validimi. Përpara se të zgjidhni 4xx, kontrolloni nëse dërguesi e trajton atë status si dështim të përhershëm. Disa platforma kanë rregullat e tyre për dorëzimet e dështuara.

Përdorni 429 me kujdes. HTTP përcakton 429 për kufizimin e normës dhe header-i Retry-After mund të tregojë se kur mund të jetë i përshtatshëm një riprovim. Megjithatë, jo çdo dërgues webhook e interpreton 429 në të njëjtën mënyrë. Nëse radha juaj është plot ose shërbimi është i mbingarkuar, konfirmoni se ofruesi do të provojë përsëri në mënyrë të sigurt dhe se orari i tij nuk do ta përkeqësojë mbingarkesën. Një radhë hyrëse e kufizuar dhe një plan backpressure zakonisht janë më të mira sesa lejimi i dështimit të paparashikueshëm të kërkesave.

Ktheni 5xx kur marrësi nuk mund ta pranojë në mënyrë të sigurt ngjarjen për shkak të një problemi të përkohshëm. Kjo përfshin një bazë të dhënash të padisponueshme, dështim të shkrimit në një radhë të qëndrueshme ose një gabim të brendshëm që pengoi validimin ose ruajtjen. Kthimi i 200 ndërsa ngjarja hidhet në heshtje e vështirëson rikuperimin sepse dërguesi nuk ka arsye të provojë përsëri.

Shmangni mbështetjen te ridrejtimet si 301, 302 ose 307 për dorëzimin e webhook-ut. Trajtimi i ridrejtimeve ndryshon midis klientëve dhe ridrejtimi i një kërkese të nënshkruar mund të krijojë paqartësi rreth destinacionit, metodës dhe trupit. Konfigurojeni ofruesin me endpoint-in përfundimtar HTTPS.

Një politikë e besueshme përgjigjeje për ngjarjet e gjurmimit

Për shumicën e integrimeve webhook të gjurmimit, politika e mëposhtme është një pikënisje e arsyeshme:

  1. Ktheni 200 ose 202 pasi ngjarja të ketë kaluar autentikimin dhe të jetë ruajtur në mënyrë të qëndrueshme ose vendosur në një radhë të besueshme.
  2. Ktheni një përgjigje 4xx për nënshkrim të pavlefshëm, autentikim të pavlefshëm ose payload përgjithmonë të papërdorshëm, duke ndjekur rregullat e dokumentuara të ofruesit.
  3. Ktheni 5xx kur një dështim i përkohshëm pengon pranimin e qëndrueshëm.
  4. Ktheni përgjigje të suksesshme për një dublikatë të njohur në mënyrë të sigurt, duke parandaluar efektet e dyfishta në biznes.
  5. Mbajeni trajtuesin të shpejtë dhe matni vonesën e konfirmimit.
  6. Testoni skenarët e timeout-it, riprovimit, dublikatave, renditjes së gabuar, payload-eve të keqformuara dhe ndërprerjes së ofruesit përpara lançimit në prodhim.

Nëse po integroni një API gjurmimi, filloni me dokumentacionin webhook të ofruesit dhe konfirmoni kodet e pranuara të suksesit, metodën e nënshkrimit të kërkesës, timeout-in, shkaqet e riprovimit, skemën e payload-it dhe identifikuesin e ngjarjes. Për integrimet 17TRACK, official Tracking API documentation është vendi i duhur për të verifikuar kontratën specifike të ofruesit në vend që ta nxirrni atë nga praktika e përgjithshme HTTP.

Lista e kontrollit për implementimin

  • Endpoint-i është i arritshëm përmes HTTPS dhe ka një URL të qëndrueshme prodhimi.
  • Autentikimi dhe verifikimi i nënshkrimit kryhen përpara përpunimit të biznesit.
  • Kërkesa e papërpunuar ose një paraqitje e verifikueshme ruhet kur kërkohet për kontrollet e nënshkrimit dhe diagnostikimin.
  • Ngjarja ruhet përpara dërgimit të përgjigjes së suksesit.
  • Dorëzimet e dyfishta janë të sigurta dhe nuk përsërisin veprime të pakthyeshme.
  • Worker-ët mund të provojnë përsëri përpunimin e brendshëm në mënyrë të pavarur nga cikli i riprovimit HTTP të dërguesit.
  • Regjistrat përfshijnë ID-në e ngjarjes, kohën e dorëzimit, kodin e përgjigjes, gjendjen e përpunimit dhe ID-në e korrelacionit pa ekspozuar sekretet.
  • Alarmet dallojnë timeout-et e endpoint-it, dështimet e validimit 4xx, ndërprerjet 5xx, vonesat e radhës dhe dorëzimet e dyfishta.
  • Sjellja e dokumentuar e ofruesit është testuar me ngjarje reale ose sandbox.

FAQ

A është 200 OK më i mirë se 202 Accepted për një webhook?

Asnjëri nuk është universalish më i mirë. Përdorni 200 OK kur kërkesa është pranuar dhe integrimi juaj e trajton përgjigjen si sukses të përgjithshëm. Përdorni 202 Accepted kur ngjarja është pranuar për përpunim asinkron. Konfirmoni që dërguesi e klasifikon përgjigjen e zgjedhur 2xx si të suksesshme.

A duhet një endpoint webhook të presë derisa përditësimi i gjurmimit të përpunohet plotësisht?

Zakonisht jo. Ai duhet të presë vetëm derisa ngjarja të autentikohet, validohet dhe pranohet në mënyrë të qëndrueshme. Puna afatgjatë normalisht duhet të ndodhë pas konfirmimit, në mënyrë që një varësi e ngadaltë të mos shkaktojë timeout dhe riprovim të shmangshëm.

Çfarë duhet të ndodhë kur e njëjta ngjarje gjurmimi mbërrin dy herë?

Njiheni duke përdorur ID-në e ngjarjes së ofruesit ose një çelës ekuivalent të projektuar me kujdes, anashkaloni efektet e dyfishta dhe ktheni përgjigje suksesi nëse ngjarja ishte pranuar tashmë. Kjo i bën riprovimet të sigurta pa fshehur dështimet e reja të përpunimit.

A duhet një nënshkrim i pavlefshëm të kthejë 400 apo 401?

Zgjedhja varet nga modeli juaj i autentikimit dhe pritshmëritë e dokumentuara të ofruesit. Të dyja mund të komunikojnë refuzim, por qëndrueshmëria ka më shumë rëndësi sesa zgjedhja universale e njërës. Mos konfirmoni një ngjarje autenticitetin e së cilës nuk mund ta verifikoni.

A shkakton gjithmonë një përgjigje 5xx riprovim?

Jo. Shumë sisteme webhook riprovojnë timeout-et dhe gabimet e serverit, por shkaqet dhe oraret e riprovimit janë specifike për ofruesin. Trajtojini riprovimet si sjellje të dokumentuar integrimi dhe verifikojini në një mjedis testimi.

Burimet