Перейти к содержанию

Повторные попытки и автоотключение

Если ваш сервер не ответил кодом 2xx или не ответил в течение 10 секунд, Pert повторяет доставку с экспоненциально увеличивающимся интервалом. Если webhook регулярно сбоит длительное время — он автоматически отключается, чтобы не нагружать обе стороны бесполезным трафиком.

Расписание повторных попыток

Интервал между попытками удваивается, начиная с 30 секунд, и ограничен сверху 2 часами. К каждому интервалу добавляется случайный джиттер ±20%, чтобы исключить «всплески» нагрузки при массовых сбоях.

Попытка Интервал (приблизительно)
1 30 секунд
2 1 минута
3 2 минуты
4 4 минуты
5 8 минут
6 16 минут
7 32 минуты
8 1 час 4 минуты
9 2 часа (максимум)
10+ 2 часа

Окно повторных попыток

Повторные попытки продолжаются в течение 24 часов с момента первой доставки. После истечения окна событие помечается как окончательно неуспешное (status = failed в истории доставок).

T+0s         T+30s   T+1m   T+2m  ...   T+24h
 │            │       │      │           │
 ▼            ▼       ▼      ▼           ▼
первый      retry   retry  retry  ...  failed
 POST        #1      #2     #3

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

Каждая попытка приходит с тем же X-Webhook-Event-Id. Используйте его как ключ дедупликации на своей стороне — одно и то же событие может быть доставлено несколько раз. См. Идемпотентность.

Что считается ошибкой

Ситуация Будет ли retry
HTTP-код 2xx за ≤ 10 секунд —
HTTP-код 4xx
HTTP-код 5xx
Таймаут запроса (> 10 секунд)
Ошибка TCP / DNS / TLS

4xx тоже триггерит retry

В отличие от некоторых сервисов, мы повторяем доставку и для 4xx. Это сделано намеренно: ошибки клиента часто временные (например, неправильная маршрутизация после деплоя). Если вы хотите окончательно отказаться от события — просто верните 2xx без обработки на своей стороне.

Автоотключение

Если 50 последовательных доставок на один и тот же webhook завершились неуспехом (включая исчерпание retry-окна), webhook автоматически переводится в статус disabled.

Что это значит:

  • На webhook не отправляются новые события, пока он в статусе disabled.
  • В истории доставок остаются все предыдущие записи.
  • События, произошедшие в период disabled, не доставляются автоматически после повторной активации.

Это защищает обе стороны от бесконечного потока бесполезных запросов на сломанный эндпоинт.

Реактивация webhook

curl -X PUT https://gateway.pert.paranoid.security/api/v1/webhooks/$WEBHOOK_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

Сначала устраните причину

Перед реактивацией убедитесь, что причина сбоев устранена. Иначе webhook быстро снова отключится, а вы пропустите ещё больше событий.

Чтобы получить события, которые произошли в период disabled или были в retry-окне, используйте Replay — он поставит в очередь повторную доставку всех retrying/failed событий за последние 7 дней.

Диагностика

Чтобы понять, почему webhook сбоит:

  1. Посмотрите историю доставок — там есть HTTP-код ответа, тело ответа (первые 4 КБ), текст ошибки и номер попытки.
  2. Если ошибки одного типа — это, скорее всего, проблема приложения.
  3. Если ошибки разные (TLS, таймаут, 5xx, ...) — возможно, инфраструктурная проблема (балансировщик, сертификат, перегрузка).