Повторная доставка (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 в теле) как ключ идемпотентности — даже если вы уже частично обработали
событие до сбоя, дубль будет распознан и проигнорирован.
См. Идемпотентность.
Сценарий восстановления после простоя
Типичный сценарий восстановления после длительной недоступности:
- Восстановите эндпоинт. Убедитесь, что он отвечает
200 OKна тестовый запрос. - Проверьте статус webhook. Если
disabled— реактивируйте черезPUT { "status": "active" }. - Сделайте replay. Проверьте результат по истории с учётом ограничения выше.
- Получите потери. События старше 7 дней через replay не доставить — для их получения сверьтесь с API списков транзакций / vault и восстановите состояние сами.
Окно — 7 дней от первой попытки
Replay ограничен replay-окном. Если первая попытка была более 7 дней назад, запись не попадает в replay независимо от того, успела ли пройти фоновая очистка. Для длительных простоев сверяйтесь с состоянием через основное API.