Skip to main content
ГлавнаяБлогРуководстваЧто должен возвращать endpoint вебхука отслеживания? Коды состояния, тайм-ауты и повторные попытки?

Что должен возвращать endpoint вебхука отслеживания? Коды состояния, тайм-ауты и повторные попытки?

17TRACK

Aдрес вебхука отслеживания должен возвращать быстрый, преднамеренный ответ 2xx после принятия события в обработку. В большинстве интеграций наиболее безопасный шаблон — аутентифицировать запрос, проверить полезную нагрузку, сохранить событие или поставить его в очередь, а затем подтвердить его с помощью 200 OK или 202 Accepted. Используйте ответы 4xx для запросов, которые отправитель не должен повторять, и ответы 5xx, если временная проблема на стороне сервера помешала принять запрос. Точные значения тайм-аута и поведение при повторных попытках по-прежнему зависят от условий работы провайдера вебхука, поэтому реализацию следует строить на основе документированного поведения отправителя, а не предположений.

Какие коды состояния и тайм-ауты должен возвращать адрес вебхука отслеживания

Для вебхука отслеживания или статуса отправления это различие важно, поскольку события доставки могут поступать более одного раза, в неправильном порядке или повторно отправляться после сбоя сети. Задача адреса не обязательно заключается в завершении каждой бизнес-операции до отправки ответа. Его первая задача — надёжно определить, принято ли событие.

Условия ответа на практике

У ответа вебхука есть две аудитории: система-отправитель и ваше приложение. Отправителю нужен понятный результат HTTP, чтобы решить, считать ли доставку успешной, повторить её или остановиться. Вашему приложению нужно достаточно времени, чтобы проверить и надёжно записать событие. Эти цели легче достигнуть, если у адреса есть небольшой синхронный путь и отдельный асинхронный путь обработки.

  1. Получить HTTP-запрос по HTTPS.
  2. Проверить подпись, учётные данные аутентификации, временную метку или другие средства проверки целостности запроса, требуемые провайдером.
  3. Разобрать и проверить полезную нагрузку, не выполняя медленные последующие операции.
  4. Записать событие либо запись дедупликации и ссылку на событие в надёжное хранилище или надёжную очередь.
  5. Вернуть преднамеренный ответ 2xx.
  6. Асинхронно обработать обновление отслеживания, уведомление клиента, изменение запасов или другое бизнес-действие.

Ответ не должен заявлять о принятии, если событие существует только в памяти процесса. Если приложение немедленно завершится после отправки успешного ответа, событие, которое не было сохранено, может быть потеряно, пока отправитель будет считать доставку успешной. Поэтому момент возврата 2xx должен соответствовать фактической гарантии сохранности данных.

Какой код состояния должен возвращать вебхук?

ОтветЗначение для отправителяТипичное использование вебхука
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 даёт отправителю, поддерживающему повторные попытки, возможность доставить событие снова, хотя провайдер может применять собственную политику.

Как обрабатывать тайм-ауты?

Значения тайм-аутов вебхуков зависят от провайдера. Универсального HTTP-тайм-аута, который используют все платформы отслеживания, не существует, и отправитель может прекратить ожидание до завершения медленной операции вашим приложением. Считайте документированный тайм-аут отправителя максимальной границей, а не целевым значением. Обычно адрес должен отвечать значительно раньше этой границы.

Самая распространённая ошибка проектирования — выполнять всю последующую работу до подтверждения вебхука. Обработчик может последовательно обращаться к базе данных, системе управления заказами, службе уведомлений и аналитическому конвейеру. Одна медленная зависимость может привести к тому, что отправитель увидит тайм-аут, даже если приложение в итоге завершит работу. Затем отправитель может повторить запрос, создав дублирующую обработку или конкурирующие обновления.

Ограничьте синхронный путь операциями, необходимыми для безопасного принятия решения. Обычно это аутентификация запроса, базовая проверка схемы, надёжное сохранение события и публикация в очередь. Дорогие операции обогащения данных, запросы к перевозчикам, сообщения клиентам и вызовы сторонних API выполняйте через рабочий процесс. Отдельно отслеживайте время получения, проверки, сохранения и подтверждения события, а также время его обработки.

Тайм-аут не равен неудачному завершению бизнес-операции. С точки зрения отправителя тайм-аут обычно означает, что он не получил пригодный успешный ответ. Ваш сервис мог успешно сохранить событие непосредственно перед закрытием соединения. Поэтому идемпотентность и дедупликация необходимы даже тогда, когда адрес кажется надёжным.

Что вызывает повторные попытки?

Отправитель вебхука может повторить запрос после ошибки соединения, тайм-аута или ответа, который согласно его условиям считается неуспешным. Точное расписание, максимальное количество попыток, алгоритм задержки и окно доставки различаются у разных провайдеров. Не обещайте фиксированное число повторных попыток, если оно не указано в документации провайдера.

Получатель должен предполагать возможность повторных попыток и специально проектировать систему с учётом этого:

  • Используйте идентификатор события, если он доступен. Сохраняйте его с уникальным ограничением или эквивалентным ключом дедупликации.
  • Сделайте обработку идемпотентной. Повторное применение одного и того же обновления статуса доставки не должно отправлять клиенту два сообщения, создавать два возврата средств или неправильно продвигать заказ.
  • Сохраняйте исходную полезную нагрузку или полезную аудиторскую запись. Это поддерживает повторное воспроизведение, расследование и сверку.
  • Разделяйте принятие и обработку. Рабочий процесс может повторять внутренние операции при сбоях, не заставляя отправителя повторять весь HTTP-обмен.
  • Записывайте коды ответов и задержку. Рост числа ответов 5xx, тайм-аутов или дублирующихся идентификаторов событий может выявить сбой до того, как пользователи сообщат об отсутствии обновлений отслеживания.

Дублирующее событие обычно должно получать успешный ответ, если исходное событие уже было надёжно принято. Возврат ошибки для каждого дубликата может вызвать ненужные повторные попытки. Адрес может записать, что событие уже встречалось, пропустить повторное бизнес-действие и вернуть тот же класс успешного ответа, который используется для вновь принятого события.

Когда возвращать 4xx, 429 или 5xx?

Возвращайте 4xx, если повторение того же запроса вряд ли устранит проблему. Примеры: недействительная подпись, отсутствие обязательной аутентификации, неподдерживаемая форма полезной нагрузки или запрос, нарушающий постоянное правило проверки. Перед выбором 4xx проверьте, считает ли отправитель этот статус окончательной ошибкой. Некоторые платформы применяют собственные правила для неудачных доставок.

Используйте 429 осторожно. HTTP определяет 429 для ограничения частоты запросов, а заголовок Retry-After может сообщить, когда повторная попытка будет уместна. Однако не каждый отправитель вебхуков интерпретирует 429 одинаково. Если очередь заполнена или сервис перегружен, убедитесь, что провайдер будет безопасно повторять запросы и что его расписание повторных попыток не усилит перегрузку. Ограниченная очередь приёма и план управления обратным давлением обычно лучше, чем непредсказуемый отказ запросов.

Возвращайте 5xx, если получатель не может безопасно принять событие из-за временной проблемы. Сюда относятся недоступная база данных, ошибка записи в надёжную очередь или внутренняя ошибка, помешавшая проверке или сохранению. Возврат 200 при незаметном удалении события усложняет восстановление, поскольку у отправителя не будет причины повторить запрос.

Не полагайтесь на перенаправления вроде 301, 302 или 307 при доставке вебхуков. Обработка перенаправлений различается у клиентов, а перенаправление подписанного запроса может создать неоднозначность относительно назначения, метода и тела. Вместо этого настройте у провайдера конечный адрес HTTPS.

Надёжная политика ответов для событий отслеживания

Для большинства интеграций с вебхуками отслеживания разумной отправной точкой будет следующая политика:

  1. Возвращайте 200 или 202 после того, как событие прошло аутентификацию и было надёжно сохранено или помещено в надёжную очередь.
  2. Возвращайте ответ 4xx для недействительной подписи, некорректной аутентификации или навсегда непригодной полезной нагрузки в соответствии с документированными правилами провайдера.
  3. Возвращайте 5xx, если временный сбой препятствует надёжному принятию.
  4. Возвращайте успешный ответ для безопасно распознанного дубликата, предотвращая повторные бизнес-эффекты.
  5. Поддерживайте высокую скорость работы обработчика и измеряйте задержку подтверждения.
  6. До запуска в рабочей среде протестируйте сценарии тайм-аутов, повторных попыток, дубликатов, событий в неправильном порядке, некорректных данных и сбоя провайдера.

Если вы интегрируете API отслеживания, начните с документации провайдера по вебхукам и подтвердите допустимые успешные коды, способ подписи запросов, тайм-аут, условия повторных попыток, схему полезной нагрузки и идентификатор события. Для интеграций 17TRACK подходящим местом для проверки условий конкретного провайдера является официальная документация Tracking API, а не общая практика HTTP.

Контрольный список реализации

  • Адрес доступен по HTTPS и имеет стабильный URL рабочей среды.
  • Аутентификация и проверка подписи выполняются до бизнес-обработки.
  • Исходный запрос или проверяемое представление сохраняется там, где это требуется для проверки подписи и устранения неполадок.
  • Событие сохраняется до отправки успешного ответа.
  • Повторные доставки безопасны и не повторяют необратимые действия.
  • Рабочие процессы могут повторять внутреннюю обработку независимо от цикла повторных HTTP-попыток отправителя.
  • Журналы содержат идентификатор события, время доставки, код ответа, состояние обработки и идентификатор корреляции, не раскрывая секреты.
  • Оповещения различают тайм-ауты адреса, ошибки проверки 4xx, сбои 5xx, задержки очереди и повторные доставки.
  • Документированное поведение провайдера протестировано с реальными событиями или событиями песочницы.

Часто задаваемые вопросы

Что лучше для вебхука: 200 OK или 202 Accepted?

Ни один вариант не является универсально лучшим. Используйте 200 OK, когда запрос принят и ваша интеграция рассматривает ответ как общий успешный результат. Используйте 202 Accepted, когда событие принято для асинхронной обработки. Убедитесь, что отправитель считает выбранный ответ 2xx успешным.

Должен ли адрес вебхука ждать полной обработки обновления отслеживания?

Обычно нет. Он должен ждать только аутентификации, проверки и надёжного принятия события. Длительные операции обычно следует выполнять после подтверждения, чтобы медленная зависимость не вызвала предотвратимый тайм-аут и повторную попытку.

Что делать, если одно и то же событие отслеживания поступило дважды?

Распознайте его по идентификатору события провайдера или тщательно разработанному эквивалентному ключу, пропустите дублирующие побочные эффекты и верните успешный ответ, если событие уже было принято. Это делает повторные попытки безопасными, не скрывая новые ошибки обработки.

Должна ли недействительная подпись возвращать 400 или 401?

Выбор зависит от вашей модели аутентификации и документированных ожиданий провайдера. Оба кода могут сообщать об отклонении, но последовательность важнее универсального выбора одного из них. Не подтверждайте событие, подлинность которого невозможно проверить.

Всегда ли ответ 5xx вызывает повторную попытку?

Нет. Многие системы вебхуков повторяют запросы после тайм-аутов и серверных ошибок, но условия и расписание повторных попыток зависят от провайдера. Рассматривайте повторные попытки как документированное поведение интеграции и проверяйте его в тестовой среде.

Источники