Доставки та повтори

Публікація події створює одну доставку для кожного ендпоінта, підписаного на її тип. Доставка — це одиниця, яку ми надсилаємо, повторюємо й записуємо: ви бачите кожну її спробу й те, що повернулося у відповідь, і можете надіслати її знову, коли потрібно.

Стани доставки

Стан	Значення
`queued`	Чекає на першу спробу.
`sending`	Спроба триває.
`sent`	Ендпоінт відповів 2xx. Готово.
`failed`	Остання спроба не вдалася, і заплановано наступну (`next_attempt_at`).
`dead`	Спроби вичерпано, або доставку не надіслано, бо її ендпоінт спершу має пройти верифікацію. Зберігається в dead-letter черзі, доки ви не надішлете її знову.

Будь-що, крім 2xx, вважається невдачею: статус 4xx чи 5xx, тайм-аут, помилка зʼєднання чи TLS. Кожна спроба чекає на відповідь до 10 секунд або стільки, скільки задано у власному delivery_timeout_ms ендпоінта (від 100 мс до 60 с).

Розклад повторів

Невдалу доставку повторюють через 30 секунд, потім через 1, 2, 4 і 8 хвилин, щоразу подвоюючи паузу аж до години між спробами, доки не буде досягнуто max_attempts ендпоінта. Ваш план обмежує max_attempts (5 на Free, 8 на Starter, 10 на Pro).

Якщо стандартна крива не підходить отримувачу, задайте ендпоінту retry_schedule — затримку в секундах перед кожним повтором:

Shell

curl -sX PATCH https://webhooks.nimbusnexus.net/v1/endpoints/ep_3f9a… \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"retry_schedule": [10, 60, 300, 1800]}'

Кожна спроба надсилає ті самі байти, наново підписані зі свіжим timestamp, тож доставка, що дійшла на годину пізніше, усе одно проходить перевірку.

Коли ендпоінт постійно падає

Після 20 невдач поспіль ендпоінт вимикається автоматично, із записом причини, і ми надсилаємо операційний вебхук endpoint.disabled, щоб ви про це дізналися. Нові події на нього більше не розгалужуються. Виправте отримувача, потім увімкніть ендпоінт (POST /v1/endpoints/{id}/enable або Enable у консолі) і повторно доставте те, що він пропустив.

Як побачити, що сталося

У консолі на сторінці Deliveries перелічено всі доставки з їхнім статусом, спробами й останньою помилкою; відкрийте доставку, щоб побачити кожну спробу — код статусу, помилку, тривалість — і надісланий payload. Через API:

Shell

curl -s "https://webhooks.nimbusnexus.net/v1/deliveries?status=failed&endpoint_id=ep_3f9a…" \
  -H "Authorization: Bearer $READ_KEY"

curl -s https://webhooks.nimbusnexus.net/v1/deliveries/dlv_…/attempts \
  -H "Authorization: Bearer $READ_KEY"

Якщо розгортання їх записує, спроба також містить початок тіла відповіді ендпоінта й заголовки, які ми надіслали (з прихованими обліковими даними).

Повторне надсилання

Що	Як
Одна доставка	`POST /v1/deliveries/{id}/redeliver` — зі стану `dead`, `failed` або `sent`.
Усі мертві (або невдалі) доставки	`POST /v1/deliveries/redeliver` з `{"status": "dead"}`, за потреби з обмеженням за `endpoint_id` або `project_id`.
Доставки за проміжок часу	`POST /v1/deliveries/replay` з `from`, `to` і `status` — для випадків на кшталт «отримувач лежав з 02:00 до 04:00». Лише для ключів `admin`; щонайбільше 10 000 за виклик.
Подія — на ендпоінт на ваш вибір	`POST /v1/events/{id}/replay` з `{"endpoint_id": "ep_…"}` — навіть на той, що не був підписаний. Лише для ключів `admin`.

Усі чотири способи створюють нові спроби збереженої події; вони не публікують нову подію, тож ідентифікатор події, за яким дедуплікує ваш ендпоінт, лишається тим самим. Ендпоінт, який має пройти верифікацію, але не пройшов, отримує відмову (409 endpoint_not_verified) або, у двох масових варіантах, пропускається й враховується в skipped_unverified.

Операційні вебхуки

Щоб дізнаватися про проблеми з доставкою, не стежачи за консоллю, підпишіть власний ендпоінт на наші операційні події: endpoint.disabled, endpoint.degraded, endpoint.recovered і message.attempt.exhausted (доставка перейшла в dead). Додайте його в розділі Operational webhooks у консолі або через POST /v1/operational-endpoints. Вони підписуються так само, як будь-яка інша доставка.

Скільки зберігаються доставки

Події, їхні доставки та спроби зберігаються 90 днів.

Що далі

Верифікація ендпоінтів — чому відповідний ендпоінт може не отримати жодної доставки.
Перевірка підпису — перевірка кожної доставки на вашому боці.
Огляд Webhooks — події, ендпоінти й підписки.