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

MarkdownChatGPTClaude

Надёжность вебхуков зависит как от поведения вашего эндпоинта, так и от гарантий доставки со стороны 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 как развивающуюся конфигурацию:

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