Перейти к основному содержимому

Безопасность

Надёжность вебхуков зависит как от поведения вашего эндпоинта, так и от гарантий доставки со стороны Unico. На этой странице описаны три инварианта, которым должен соответствовать ваш эндпоинт: идемпотентность, ограничение параллелизма и частота ошибок.

Идемпотентность​

Реализация вебхуков Unico гарантирует доставку хотя бы один раз — один и тот же статус может быть отправлен более одного раза для одного и того же processId. Ваш эндпоинт должен быть идемпотентным.

Рекомендуемый паттерн:

  1. При каждом вызове вебхука сначала проверьте, был ли processId уже обработан.
  2. Если да — немедленно верните 2xx (работа уже выполнена).
  3. Если нет — примените бизнес-логику и сохраните информацию о том, что этот processId был обработан.
// pseudo-code
async function handleWebhook(req, res) {
  const { processId } = req.body;

  if (await alreadyProcessed(processId)) {
    return res.status(200).end();
  }

  await applyBusinessLogic(req.body);
  await markAsProcessed(processId);
  return res.status(200).end();
}
Почему это важно

Неидемпотентный эндпоинт, выполняющий бизнес-логику при каждой доставке (например, списывающий деньги с карты или отправляющий email), будет срабатывать повторно при каждой повторной попытке — а повторные попытки являются нормой, а не исключением при доставке вебхуков.

Ограничение параллелизма​

Чтобы защитить ваш эндпоинт от всплесков нагрузки в периоды высокой активности, при регистрации вебхука задайте максимальное количество одновременных активных доставок (максимум: 500).

При достижении лимита параллелизма Unico ставит дополнительные доставки в очередь и обрабатывает их по мере освобождения ресурсов. В сочетании с механизмом повторных попыток это означает, что продолжительный всплеск может увеличить фактическое время доставки новых вебхуков.

Частота ошибок​

Частота ошибок (ответы вне диапазона 200–299) должна всегда оставаться низкой. Если ваш эндпоинт начинает возвращать ошибки в масштабе, Unico автоматически снижает пропускную способность вебхуков для этого эндпоинта. В сочетании с механизмом повторных попыток это может значительно увеличить время выполнения новых вебхуков.

Операционные рекомендации:

  • Отслеживайте ответы не-2xx на своей стороне. Настройте оповещения при устойчивом превышении нормального уровня ошибок.
  • Относитесь к обработчику вебхуков как к критическому пути — он должен быть одним из наиболее надёжных сервисов в вашем стеке.
  • При плановом техническом обслуживании предпочтительнее останавливать приём трафика на уровне балансировщика нагрузки, а не возвращать 503. Устойчивые ответы не-2xx — включая 503 — активируют автоматическое снижение пропускной способности, описанное выше; когда ваш эндпоинт восстановится, сниженная пропускная способность задержит доставку событий, накопившихся во время простоя. Не возвращайте 200 для необработанных событий.

Семантика статусов​

Воспринимайте набор значений state и lastEvent как развивающуюся конфигурацию:

  • Реагируйте только на состояния / события, которые вы явно обрабатываете.
  • Логируйте неизвестные значения — не генерируйте ошибки при их получении.
  • Новые состояния могут быть добавлены без изменения мажорной версии.
Последнее обновление