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

Повторная доставка (replay)

Если ваш сервер был временно недоступен и вы хотите получить пропущенные события — используйте эндпоинт replay. Он ставит в очередь повторную доставку всех событий webhook, которые сейчас в статусе retrying или failed и произошли в пределах 7-дневного replay-окна.

Retry-окно ≠ Replay-окно

  • Retry-окно (24 часа) — пока Pert автоматически повторяет доставку события. По истечении 24 часов от первой попытки событие переводится в статус failed.
  • Replay-окно (7 дней) — на сколько назад вы можете вручную перезапустить доставку через POST /replay. Отбираются существующие записи retrying и failed, если они моложе 7 дней.

После 7 дней запись выходит из replay-окна и подлежит фоновой очистке.

Текущее ограничение повторной доставки

replayed_count считает записи, возвращённые в очередь, а не HTTP-доставки. Окно автоматических повторов при replay не начинается заново: записи старше 24 часов снова переходят в failed без отправки. Для такого простоя восстанавливайте состояние через API. События, возникшие при inactive или disabled, не создают записи доставки для этого webhook.

Когда использовать replay

Ситуация Что делать
Записи доставки моложе 24 часов Replay возобновит обработку существующих неуспешных записей
Webhook был автоотключён (disabled) Сначала реактивируйте, затем сделайте replay
Сервер был недоступен > 7 дней Replay не поможет — события вне replay-окна
Хочется заново обработать уже доставленные события Replay не нужен — события в success он не трогает

Replay не воспроизводит успешные события

Replay перезапускает доставку только тех событий, которые сейчас в статусе retrying или failed. События, успешно доставленные ранее, повторно не отправляются.

Запрос

curl -X POST https://gateway.pert.paranoid.security/api/v1/webhooks/$WEBHOOK_ID/replay \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

Ответ

{
  "replayed_count": 42
}
Поле Тип Описание
replayed_count int Количество событий, поставленных в очередь повторной доставки

Обработка очереди запускается примерно каждые 30 секунд; это период проверки, а не гарантия срока доставки всей очереди. Webhook должен быть active.

Дедупликация

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

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

Сценарий восстановления после простоя

Типичный сценарий восстановления после длительной недоступности:

  1. Восстановите эндпоинт. Убедитесь, что он отвечает 200 OK на тестовый запрос.
  2. Проверьте статус webhook. Если disabled — реактивируйте через PUT { "status": "active" }.
  3. Сделайте replay. Проверьте результат по истории с учётом ограничения выше.
  4. Получите потери. События старше 7 дней через replay не доставить — для их получения сверьтесь с API списков транзакций / vault и восстановите состояние сами.

Окно — 7 дней от первой попытки

Replay ограничен replay-окном. Если первая попытка была более 7 дней назад, запись не попадает в replay независимо от того, успела ли пройти фоновая очистка. Для длительных простоев сверяйтесь с состоянием через основное API.