Вебхук-обработчик
Общие требования к endpoint
Ваш сервер-обработчик должен соответствовать следующим сетевым требованиям:
- Протокол: только HTTPS (TLS 1.2+).
- Порт: 443 или 8443.
- TLS: действительный сертификат от доверенного удостоверяющего центра.
- Public URL: адрес должен быть доступен из внешней сети (запрещено использование 127.0.0.1 или localhost).
- Метод: POST.
Структура запроса
Заголовки
- X-WH-Webhook-Time – время отправки сообщения веб-хука (Unix time);
- X-WH-Request-Id – идентификатор исходящего запроса (уникальный идентификатор для каждой конкретной доставки вебхука);
Content-Length: 148
Content-Type: application/json
X-WH-Webhook-Time: 1622552400000
X-WH-Request-Id: 714d887e-3fae-45f0-9cd6-63538630bc13
Тело запроса
Все типы событий имеют одинаковую верхнеуровневую структуру:
- content: содержит подробную информацию о конкретном событии (структура content может меняться в зависимости от типа события);
- eventType: тип события в формате Cущность.Cобытие;
- eventVersion: версия события;
- eventTime: время возникновения события в формате (ISO 8601).
{
"content": {
//object
},
"eventType": "eventType",
"eventVersion": "eventVersion",
"eventTime": "YYYY-MM-DDThh:mm:ss.sssZ"
}
Требования к обработке
Чтобы подтвердить получение события, сервер должен вернуть статус 2xx максимум за 60 секунд.
Если вашему приложению требуется больше времени или возвращен один из статусов: 408, 409, 429, 500, 502, 503, 504, 507, 508 или 509, банк сочтет доставку неуспешной и предпримет повторную попытку.
Все остальные статус-коды считаются финальными — после них повторные попытки не выполняются.
Политика повторных попыток
Банк использует стратегию экспоненциальной задержки. Максимальное количество запросов на одно событие — 11 (первая отправка и 10 повторов).
Задержки между попытками увеличиваются по графику: сразу, через 5 секунд, через 5 минут, через 30 минут, через 2 часа, через 5 часов, через 10 часов, через 14 часов, через 20 часов и через 24 часа.
| Попытка | Задержка относительно предыдущей | Время от старта |
|---|---|---|
| 1 | Немедленно | 00:00:00 |
| 2 | 5 секунд | 00:00:05 |
| 3 | 5 минут | 00:05:05 |
| 4 | 30 минут | 00:35:05 |
| 5 | 2 часа | 02:35:05 |
| 6 | 5 часов | 07:35:05 |
| 7 | 10 часов | 17:35:05 |
| 8 | 14 часов | 31:35:05 |
| 9 | 20 часов | 51:35:05 |
| 10 | 24 часа | 75:35:05 |
Правила обработки
Обработка новых полей
Банк может добавлять новые поля в content. Ваша система должна корректно реагировать на новые поля.
Дедупликация
Банк доставляет уведомления по принципу "как минимум один раз".
Это означает, что одно и то же событие может быть отправлено несколько раз (например, из-за таймаутов, сетевых проблем или повторных попыток).
Кроме того, последовательность событий может нарушаться: второе по времени изменение может прийти раньше первого. Важно правильно реагировать на такие события.
Подробнее о дедупликации для конкретных типов событий в документации: