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

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

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

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

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

После 7 дней запись о доставке удаляется и replay становится невозможен.

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

Ситуация Что делать
Сервер был недоступен < 7 дней 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 секунд (на ближайшем тике retry-цикла).

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

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

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

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

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

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

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

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