Какво трябва да връща един webhook endpoint за проследяване? Кодове на състоянието, изчаквания и повторни опити?
Крайната точка на tracking webhook трябва да върне бърз, преднамерен отговор от клас 2xx, след като е приела събитието за обработка. При повечето интеграции най-сигурният модел е да удостоверите заявката, да валидирате полезния товар, да съхраните или поставите събитието в опашка и да потвърдите получаването му с 200 OK или 202 Accepted. Използвайте отговори 4xx за заявки, които изпращачът не трябва да опитва отново, и отговори 5xx, когато временен проблем от страна на сървъра е попречил на приемането. Точните стойности за изчакване и поведението при повторен опит все пак зависят от договора с доставчика на webhook-а, затова реализацията ви трябва да бъде проектирана според документираното поведение на изпращача, а не според предположения.
При webhook за проследяване или за статус на пратка това разграничение е важно, защото събитията за доставка могат да пристигнат повече от веднъж, да пристигнат в неправилен ред или да бъдат възпроизведени след мрежова повреда. Задачата на крайната точка не е непременно да завърши всяка бизнес операция, преди да отговори. Първата ѝ задача е надеждно да реши дали събитието е прието.
Договорът за отговора на практика
Отговорът на webhook има две аудитории: изпращащата система и собственото ви приложение. Изпращачът се нуждае от ясен HTTP резултат, за да реши дали да маркира доставката като успешна, да опита отново или да спре. Приложението ви се нуждае от достатъчно време, за да провери и надеждно да запише събитието. Тези цели се постигат по-лесно, когато крайната точка има малък синхронен път и отделен асинхронен път за обработка.
- Получете HTTP заявката през HTTPS.
- Проверете подписа, идентификационните данни за удостоверяване, времевия печат или други контроли за целостта на заявката, изисквани от доставчика.
- Парсирайте и валидирайте полезния товар, без да извършвате бавна последваща работа.
- Запишете събитието или запис за дедупликация и референция към събитието в надеждно хранилище или надеждна опашка.
- Върнете преднамерен отговор 2xx.
- Обработете асинхронно актуализацията за проследяване, уведомяването на клиента, промяната в наличността или друго бизнес действие.
Отговорът не трябва да заявява приемане, ако събитието съществува само в паметта на процеса. Ако приложението се срине непосредствено след връщането на успех, събитие, което никога не е било запазено, може да бъде загубено, докато изпращачът смята, че доставката е успешна. Следователно моментът, в който връщате 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 на трети страни зад worker. Наблюдавайте отделно времето за получаване, валидиране, запазване и потвърждаване на събитието от времето за обработката му.
Изчакването не е същото като неуспешна бизнес операция. От гледна точка на изпращача изчакването обикновено означава, че той не е получил използваем успешен отговор. Услугата ви може да е съхранила събитието успешно точно преди връзката да бъде прекъсната. Затова идемпотентността и дедупликацията са необходими дори когато крайната точка изглежда надеждна.
Какво причинява повторните опити?
Изпращачът на webhook може да опита отново след грешка във връзката, изчакване или отговор, който договорът му класифицира като неуспешен. Точният график, максималният брой опити, алгоритъмът за обратно изчакване и прозорецът за доставка варират според доставчика. Не обещавайте фиксиран брой повторни опити, освен ако това не е посочено в документацията на доставчика.
Получателят трябва да приеме, че повторни опити могат да се случат, и умишлено да проектира системата за тях:
- Използвайте идентификатор на събитието, когато е наличен. Съхранявайте го с уникално ограничение или еквивалентен ключ за дедупликация.
- Направете обработката идемпотентна. Прилагането на една и съща актуализация за статуса на доставка два пъти не трябва да изпраща две съобщения до клиента, да създава два рефънда или да придвижва поръчка неправилно.
- Запазвайте оригиналния полезен товар или полезен одитен запис. Това подпомага възпроизвеждането, разследването и съгласуването.
- Разделяйте приемането от обработката. Worker може да повтаря вътрешни неуспешни операции, без да принуждава изпращача да повтаря целия HTTP обмен.
- Записвайте кодовете на отговора и латентността. Увеличение на отговорите 5xx, изчакванията или дублираните идентификатори на събития може да разкрие прекъсване, преди потребителите да съобщят за липсващи актуализации за проследяване.
Дублирано събитие обикновено трябва да получи успешен отговор, ако оригиналното събитие вече е било надеждно прието. Връщането на грешка за всеки дубликат може да предизвика ненужни повторни опити. Крайната точка може да запише, че събитието е било видяно преди, да пропусне повторното бизнес действие и да върне същия клас успешен отговор, използван за новоприето събитие.
Кога трябва да връщате 4xx, 429 или 5xx?
Връщайте 4xx, когато повторното изпращане на същата заявка вероятно няма да реши проблема. Примери са невалиден подпис, липсващо задължително удостоверяване, неподдържана форма на полезния товар или заявка, която нарушава постоянно правило за валидиране. Преди да изберете 4xx, проверете дали изпращачът третира този статус като окончателна грешка. Някои платформи имат собствени правила за неуспешни доставки.
Използвайте 429 внимателно. HTTP дефинира 429 за ограничаване на честотата, а заглавката Retry-After може да съобщи кога повторният опит би бил подходящ. Не всеки изпращач на webhook обаче интерпретира 429 по един и същи начин. Ако опашката ви е пълна или услугата ви е претоварена, потвърдете, че доставчикът ще опита отново безопасно и че графикът му няма да влоши претоварването. Ограничена входяща опашка и план за обратен натиск обикновено са по-добри от непредсказуемото допускане на неуспешни заявки.
Връщайте 5xx, когато получателят не може безопасно да приеме събитието поради временен проблем. Това включва недостъпна база данни, неуспешно записване в надеждна опашка или вътрешна грешка, попречила на валидирането или запазването. Връщането на 200 при тихо изпускане на събитието затруднява възстановяването, тъй като изпращачът няма причина да опита отново.
Избягвайте да разчитате на пренасочвания като 301, 302 или 307 за доставяне на webhook. Обработката на пренасочванията се различава между клиентите, а пренасочването на подписана заявка може да създаде неяснота относно местоназначението, метода и тялото. Конфигурирайте доставчика с крайната HTTPS крайна точка.
Надеждна политика за отговори при събития за проследяване
За повечето интеграции на tracking webhook следната политика е разумна отправна точка:
- Връщайте
200или202, след като събитието е преминало удостоверяване и е било надеждно съхранено или поставено в надеждна опашка. - Връщайте отговор 4xx за невалиден подпис, невалидно удостоверяване или окончателно неизползваем полезен товар, съгласно документираните правила на доставчика.
- Връщайте 5xx, когато временна повреда възпрепятства надеждното приемане.
- Връщайте успешен отговор за безопасно разпознат дубликат, като предотвратявате дублирани бизнес ефекти.
- Поддържайте обработчика бърз и измервайте латентността на потвърждението му.
- Тествайте сценарии с изчакване, повторен опит, дубликати, неправилен ред, невалидни данни и прекъсване на доставчика преди стартиране в продукция.
Ако интегрирате tracking API, започнете с документацията за webhook на доставчика и потвърдете приетите кодове за успех, метода за подписване на заявките, изчакването, условията за повторен опит, схемата на полезния товар и идентификатора на събитието. За интеграции с 17TRACK подходящото място за проверка на специфичния за доставчика договор е официалната документация на Tracking API, вместо да го извеждате от общата практика при HTTP.
Контролен списък за реализация
- Крайната точка е достъпна през HTTPS и има стабилен производствен URL.
- Удостоверяването и проверката на подписа се извършват преди бизнес обработката.
- Суровата заявка или проверимо представяне се запазва, когато е необходимо за проверка на подписа и отстраняване на проблеми.
- Събитието се запазва, преди да бъде изпратен успешният отговор.
- Дублираните доставки са безопасни и не повтарят необратими действия.
- Worker-ите могат да повтарят вътрешната обработка независимо от 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 — дефиниции за успешни отговори, клиентски грешки, сървърни грешки, пренасочване и обработка на отговори.
- RFC 6585: Допълнителни HTTP кодове за състояние — спецификация за
429 Too Many Requests. - Документация на Stripe за Webhooks — практически насоки за отговорите на webhook, асинхронната обработка и обработката на дублирани събития.
- GitHub Docs: Обработка на доставки на Webhook — проверка на доставките и оперативни съображения за интеграции с webhook.
- Документация на 17TRACK Tracking API — специфична за доставчика документация, която трябва да бъде проверена при реализиране на интеграции с tracking API.


