Skip to main content
ДомаБлогВодичиШто треба да враќа крајната точка на webhook-от за следење? Статусни кодови, временски ограничувања и повторни обиди?

Што треба да враќа крајната точка на webhook-от за следење? Статусни кодови, временски ограничувања и повторни обиди?

17TRACK

Крајната точка на webhook-от за следење треба да врати брз, намерен 2xx одговор откако ќе го прифати настанот за обработка. Во повеќето интеграции, најбезбедниот пристап е да се автентицира барањето, да се проверат податоците, да се зачува или стави во редица настанот и да се потврди со 200 OK или 202 Accepted. Користете 4xx одговори за барања што испраќачот не треба повторно да ги испрати, а 5xx одговори кога привремен проблем на серверот спречил прифаќање. Точното однесување при истек на времето и повторно испраќање сепак зависи од договорот со обезбедувачот на webhook-от, па имплементацијата треба да биде заснована на документираното однесување на испраќачот, а не на претпоставки.

Кои статусни кодови и временски ограничувања треба да ги враќа крајната точка на webhook-от за следење

За webhook за следење или статус на пратка, оваа разлика е важна бидејќи настаните за испорака може да пристигнат повеќе од еднаш, по различен редослед или повторно да бидат испратени по мрежен дефект. Задачата на крајната точка не е нужно да ја заврши секоја деловна операција пред да одговори. Нејзината прва задача е сигурно да одлучи дали настанот е прифатен.

Договорот за одговор во практична смисла

Одговорот на webhook-от има две публики: системот што испраќа и вашата сопствена апликација. На испраќачот му е потребен јасен HTTP резултат за да одлучи дали успешно да ја означи испораката, повторно да ја испрати или да престане. На вашата апликација ѝ е потребно доволно време да го провери и трајно да го запише настанот. Овие цели полесно се постигнуваат кога крајната точка има кратка синхрона патека и одделна асинхрона патека за обработка.

  1. Примете го HTTP барањето преку HTTPS.
  2. Проверете го потписот, акредитивите за автентикација, временскиот печат или другите контроли за интегритет на барањето што ги бара обезбедувачот.
  3. Парсирајте ги и проверете ги податоците без извршување бавна работа со надворешни зависности.
  4. Запишете го настанот, или записот за дедупликација и референцата кон настанот, во трајно складиште или сигурна редица.
  5. Вратете намерен 2xx одговор.
  6. Обработете го ажурирањето за следење, известувањето на клиентот, промената на залихите или друга деловна активност асинхроно.

Одговорот не треба да тврди дека настанот е прифатен ако тој постои само во меморијата на процесот. Ако апликацијата падне веднаш по враќањето на успешен одговор, настанот што никогаш не бил зачуван може да се изгуби, додека испраќачот верува дека испораката била успешна. Затоа, моментот кога враќате 2xx треба да одговара на вашата вистинска гаранција за трајност.

Кој статусен код треба да го враќа webhook-от?

ОдговорЗначење за испраќачотТипична употреба на webhook
200 OKБарањето е прифатено и успешно обработено.Практичен стандарден избор по проверката и трајното прифаќање.
202 AcceptedБарањето е прифатено за обработка, но работата може да продолжи.Корисно кога настанот е безбедно ставен во редица, но деловната обработка е асинхрона.
204 No ContentБарањето е успешно и не е потребно тело на одговорот.Соодветно кога обезбедувачот прифаќа празен успешен одговор.
400–499Барањето е невалидно, неавторизирано или неприфатливо во испратената форма.Неисправни податоци, неуспешна автентикација, невалиден потпис или трајно одбиен настан.
429 Too Many RequestsПримачот применува ограничување на бројот на барања.Користете го само кога однесувањето при повторно испраќање на испраќачот и вашата политика за ограничување се усогласени.
500–599Примачот не можел да го прифати барањето поради проблем на серверот или привремен проблем.Недостапна база на податоци, неуспешна редица, неуспешна зависност или неочекувана грешка во апликацијата.

200 OK често е најмалку изненадувачкиот избор бидејќи широко се разбира како успешно примање. 202 Accepted исто така е семантички корисен кога крајната точка го прифатила настанот за подоцнежна обработка. Ниту еден код не е автоматски точен: документацијата на испраќачот може да дефинира кои 2xx одговори се сметаат за успешни, а некои обезбедувачи може да очекуваат одредено тело или тип на содржина.

Не враќајте 2xx одговор само затоа што HTTP барањето стигнало до вашиот сервер. Ако проверката на потписот не успее или податоците не може безбедно да се протолкуваат, 4xx одговорот обично е поискрена опција. Спротивно на тоа, не враќајте 4xx за привремена недостапност на базата на податоци ако настанот може да успее подоцна. 5xx одговорот му дава на испраќачот што поддржува повторно испраќање можност повторно да го испорача настанот, иако обезбедувачот може да применува сопствена политика.

Како треба да се постапува со истекот на времето?

Вредностите за истек на времето на webhook-от се специфични за обезбедувачот. Не постои универзално HTTP временско ограничување што го користи секоја платформа за следење, а испраќачот може да престане да чека пред вашата апликација да заврши бавна операција. Документираното временско ограничување на испраќачот третирајте го како максимална граница, а не како цел. Крајната точка обично треба да одговори многу пред таа граница.

Најчестата грешка во дизајнот е извршување на целата работа со надворешни системи пред потврдување на webhook-от. Обработувачот може последователно да повикува база на податоци, систем за управување со нарачки, услуга за известувања и аналитичка платформа. Една бавна зависност може да предизвика испраќачот да види истек на времето иако вашата апликација на крајот ја завршила работата. Испраќачот потоа може повторно да испрати, создавајќи дупликатна обработка или конкурентни ажурирања.

Синхроната патека ограничете ја на работата потребна за безбедна одлука за прифаќање. Тоа обично вклучува автентикација на барањето, основна проверка на шемата, трајно складирање на настанот и објавување во редица. Скапото збогатување, пребарувањата кај превозниците, испраќањето пораки до клиентите и повиците кон API-ја од трети страни извршувајте ги преку работник. Одделно следете го времето за примање, проверка, трајно зачувување и потврдување на настанот од времето поминато во неговата обработка.

Истекот на времето не е исто што и неуспешна деловна операција. Од гледна точка на испраќачот, истекот обично значи дека не добил употреблив успешен одговор. Вашата услуга можеби успешно го зачувала настанот непосредно пред да се прекине врската. Затоа идемпотентноста и дедупликацијата се неопходни дури и кога крајната точка изгледа сигурна.

Што предизвикува повторно испраќање?

Испраќачот на webhook може повторно да испрати по грешка во врската, истек на времето или одговор што неговиот договор го класифицира како неуспешен. Точниот распоред, максималниот број обиди, алгоритмот за постепено зголемување на интервалот и периодот на испорака се разликуваат според обезбедувачот. Не ветувајте фиксен број повторни обиди освен ако тоа не е наведено во документацијата на обезбедувачот.

Примачот треба да претпостави дека може да се случат повторни обиди и намерно да се подготви за нив:

  • Користете идентификатор на настанот кога е достапен. Зачувајте го со уникатно ограничување или еквивалентен клуч за дедупликација.
  • Обработката направете ја идемпотентна. Двојното применување на истото ажурирање на статусот на испораката не треба да испрати две пораки до клиентот, да создаде две рефундации или неправилно да ја унапреди нарачката.
  • Зачувајте ги оригиналните податоци или корисен запис за ревизија. Ова овозможува повторно испраќање, истрага и усогласување.
  • Одделете го прифаќањето од обработката. Работникот може повторно да ги обиде интерните неуспеси без да го принудува испраќачот повторно да ја изврши целата HTTP размена.
  • Запишувајте ги статусните кодови и доцнењето. Зголемувањето на 5xx одговорите, истекот на времето или дупликатните идентификатори на настани може да открие прекин пред корисниците да пријават исчезнати ажурирања за следење.

Дупликатниот настан обично треба да добие успешен одговор ако оригиналниот настан веќе бил трајно прифатен. Враќањето грешка за секој дупликат може да предизвика непотребни повторни обиди. Крајната точка може да забележи дека настанот бил претходно виден, да ја прескокне повторената деловна активност и да ја врати истата класа на успех што се користи за новоприфатен настан.

Кога треба да вратите 4xx, 429 или 5xx?

Вратете 4xx кога повторното испраќање на истото барање веројатно нема да го реши проблемот. Примери се невалиден потпис, недостиг на задолжителна автентикација, неподдржан формат на податоците или барање што прекршува трајно правило за проверка. Пред да изберете 4xx, проверете дали испраќачот го третира тој статус како траен неуспех. Некои платформи имаат сопствени правила за неуспешни испораки.

Користете 429 внимателно. HTTP го дефинира 429 за ограничување на бројот на барања, а заглавието Retry-After може да укаже кога повторното испраќање би било соодветно. Сепак, не секој испраќач на webhook го толкува 429 на ист начин. Ако редицата е полна или услугата е преоптоварена, потврдете дека обезбедувачот ќе испраќа повторно безбедно и дека неговиот распоред нема дополнително да го влоши преоптоварувањето. Ограничена влезна редица и план за повратен притисок обично се подобри од дозволување барањата да откажуваат непредвидливо.

Вратете 5xx кога примачот не може безбедно да го прифати настанот поради привремен проблем. Ова вклучува недостапна база на податоци, неуспешно запишување во трајна редица или интерна грешка што спречила проверка или зачувување. Враќањето 200 додека настанот тивко се отфрла ја отежнува обновата бидејќи испраќачот нема причина повторно да се обиде.

Избегнувајте потпирање на пренасочувања како 301, 302 или 307 за испорака на webhook. Обработката на пренасочувањата се разликува меѓу клиентите, а пренасочувањето на потпишано барање може да создаде нејаснотии околу одредиштето, методот и телото. Наместо тоа, конфигурирајте го обезбедувачот со крајната HTTPS адреса.

Сигурна политика за одговори за настани за следење

За повеќето интеграции со webhook за следење, следната политика е разумна почетна точка:

  1. Вратете 200 или 202 откако настанот ќе ја помине автентикацијата и ќе биде трајно зачуван или ставен во сигурна редица.
  2. Вратете 4xx одговор за невалиден потпис, невалидна автентикација или трајно неупотребливи податоци, следејќи ги документираните правила на обезбедувачот.
  3. Вратете 5xx кога привремен неуспех спречува трајно прифаќање.
  4. Вратете успешен одговор за безбедно препознаен дупликат, истовремено спречувајќи дупликатни деловни ефекти.
  5. Обработувачот нека биде брз и мерете го доцнењето на потврдата.
  6. Тестирајте сценарија со истек на времето, повторни обиди, дупликати, настани по различен редослед, неисправни податоци и прекин кај обезбедувачот пред пуштање во продукција.

Ако интегрирате API за следење, започнете со документацијата за webhook на обезбедувачот и потврдете ги прифатените успешни кодови, методот за потпишување на барањата, временското ограничување, причините за повторно испраќање, шемата на податоците и идентификаторот на настанот. За интеграциите со 17TRACK, официјалната документација за Tracking API е соодветното место за проверка на договорот специфичен за обезбедувачот, наместо негово извлекување од општата HTTP практика.

Список за проверка на имплементацијата

  • Крајната точка е достапна преку HTTPS и има стабилна продукциска URL-адреса.
  • Автентикацијата и проверката на потписот се вршат пред деловната обработка.
  • Суровото барање или проверлива репрезентација се задржува кога е потребно за проверки на потписот и отстранување проблеми.
  • Настанот се зачувува пред да се испрати успешниот одговор.
  • Дупликатните испораки се безбедни и не повторуваат неповратни дејства.
  • Работниците може повторно независно да ја обидат интерната обработка од циклусот за HTTP повторни обиди на испраќачот.
  • Дневниците содржат ID на настанот, време на испорака, код на одговор, состојба на обработка и ID за корелација без изложување тајни.
  • Известувањата ги разликуваат истекот на времето на крајната точка, 4xx неуспесите при проверка, 5xx прекините, доцнењата во редицата и дупликатните испораки.
  • Документираното однесување на обезбедувачот е тестирано со реални или sandbox настани.

Често поставувани прашања

Дали 200 OK е подобар од 202 Accepted за webhook?

Ниту еден не е универзално подобар. Користете 200 OK кога барањето е прифатено и вашата интеграција го третира одговорот како општ успех. Користете 202 Accepted кога настанот е прифатен за асинхрона обработка. Потврдете дека испраќачот го класифицира избраниот 2xx одговор како успешен.

Дали крајната точка на webhook треба да чека додека ажурирањето за следење целосно не се обработи?

Обично не. Треба да чека само додека настанот не биде автентициран, проверен и трајно прифатен. Долготрајната работа обично треба да се извршува по потврдата за да не предизвика бавната зависност непотребен истек на времето и повторно испраќање.

Што треба да се случи кога истиот настан за следење ќе пристигне двапати?

Препознајте го со ID на настанот од обезбедувачот или внимателно дизајниран еквивалентен клуч, прескокнете ги дупликатните несакани ефекти и вратете успешен одговор ако настанот веќе бил прифатен. Така повторните обиди се безбедни без прикривање на нови неуспеси во обработката.

Дали невалиден потпис треба да врати 400 или 401?

Изборот зависи од вашиот модел на автентикација и документираните очекувања на обезбедувачот. И двата може да пренесат одбивање, но доследноста е поважна од универзалниот избор на еден код. Не потврдувајте настан чија автентичност не можете да ја проверите.

Дали 5xx одговорот секогаш предизвикува повторно испраќање?

Не. Многу webhook системи повторно испраќаат по истек на времето и грешки на серверот, но причините и распоредите за повторно испраќање се специфични за обезбедувачот. Третирајте ги повторните обиди како документирано однесување на интеграцијата и проверете ги во тестна средина.

Извори

  • RFC 9110: HTTP Semantics — дефиниции за успешни одговори, грешки кај клиентот, грешки кај серверот, пренасочување и обработка на одговори.
  • RFC 6585: Additional HTTP Status Codes — спецификација за 429 Too Many Requests.
  • Stripe Webhooks Documentation — практични насоки за одговори на webhook, асинхрона обработка и ракување со дупликатни настани.
  • GitHub Docs: Handling Webhook Deliveries — проверка на испораките и оперативни согледувања за интеграции со webhook.
  • 17TRACK Tracking API Documentation — документација специфична за обезбедувачот што треба да се провери при имплементација на интеграции со API за следење.