# Вебхуки

Раздел **Вебхуки** предназначен для настройки уведомлений о событиях верификации. OneKYC отправляет HTTP-запросы на указанные вами URL-адреса при наступлении определённых событий (создание сессии, завершение шага, одобрение или отклонение верификации и другие).

## Эндпоинты [#эндпоинты]

Эндпоинт — это URL-адрес вашего сервера, на который OneKYC направляет уведомления. Допускается создание нескольких эндпоинтов для различных целей и окружений.

### Создание эндпоинта [#создание-эндпоинта]

При создании нового эндпоинта укажите следующие параметры:

- **URL** — адрес вашего сервера для приёма уведомлений. Обязательно использование протокола HTTPS.
- **Описание** — пояснение назначения эндпоинта (например, «Production CRM», «Аналитическая система»).
- **Окружение** — sandbox или production. Определяет, события какого окружения будут направляться на данный URL.
- **Типы событий** — перечень событий, уведомления о которых необходимо получать:
  - **Все события** (`*`) — уведомления обо всех типах событий.
  - **Выборочные события** — индивидуальный набор (например, `verification.approved`, `verification.declined`, `step.completed`).
  - **KYB-события** — события, связанные с верификацией юридических лиц (например, `kyb.business.verified`), доступны в отдельной категории.

Полный перечень типов событий приведён в разделах: [Вебхуки API](/ru/api/webhooks), [KYB Вебхуки](/ru/kyb/webhooks).

### Секрет подписи [#секрет-подписи]

После создания эндпоинта система генерирует **секрет подписи** с префиксом `whsec_`. Секрет используется для верификации подлинности входящих запросов на вашей стороне.

> Секрет отображается **однократно** при создании. Сохраните его в защищённом хранилище немедленно.

### Ротация секрета [#ротация-секрета]

При необходимости обновления секрета (плановая ротация или подозрение на компрометацию):

1. Откройте карточку эндпоинта.
2. Инициируйте ротацию секрета.
3. В течение **периода грации** оба секрета (старый и новый) принимаются системой одновременно, что позволяет обновить код проверки подписи на вашей стороне без потери уведомлений.
4. По истечении периода грации старый секрет прекращает действие.

## Журнал доставок [#журнал-доставок]

В подразделе **«Логи»** (или **«Deliveries»**) отображается история отправки уведомлений:

| Поле | Описание |
|------|----------|
| **Время** | Дата и время отправки |
| **URL** | Адрес эндпоинта |
| **Событие** | Тип отправленного события |
| **Статус ответа** | HTTP-код ответа вашего сервера (2xx — успех, иное — ошибка) |
| **Попытки** | Количество попыток доставки |

При открытии детальной информации о доставке доступны: тело запроса, заголовки и ответ вашего сервера. Это позволяет диагностировать проблемы с приёмом уведомлений и проверкой подписи.

### Повторная отправка [#повторная-отправка]

Для конкретной доставки, завершившейся ошибкой, доступна функция **«Повторить отправку»** (Resend) — уведомление будет направлено повторно на тот же эндпоинт.

## Политика повторных попыток [#политика-повторных-попыток]

При неуспешной доставке (ваш сервер не ответил или вернул код ошибки) OneKYC выполняет автоматические повторные попытки:

- **Максимальное количество попыток** — до 5.
- **Стратегия** — экспоненциальный backoff: базовая задержка 5 секунд, удваивается на каждой попытке, верхний предел 24 часа. Дополнительно применяется случайный jitter ±20 % для размазывания нагрузки.
- При исчерпании всех попыток событие помещается в очередь недоставленных сообщений (Dead Letter Queue) — см. ниже.

## Очередь недоставленных сообщений (Dead Letter Queue) [#очередь-недоставленных-сообщений-dead-letter-queue]

В подразделе **Dead Letter Queue** доступны события, для которых исчерпаны все автоматические попытки доставки. Возможные действия:

- **Повторная отправка отдельного события** (`Retry`) — уведомление направляется повторно на тот же эндпоинт.
- **Массовый retry** (`Retry all`) — повторная отправка всех событий из DLQ для выбранного эндпоинта (обычно используется после восстановления работоспособности приёмника).
- **Удаление события** (`Delete`) — событие исключается из DLQ без отправки.

Все массовые действия и retry фиксируются в журнале аудита.

## Статистика и примеры payload [#статистика-и-примеры-payload]

- **Статистика доставок** — сводные показатели по эндпоинту (количество отправок, успешных доставок, ошибок, среднее время ответа).
- **Пример payload** для каждого типа события — показывает структуру тела запроса, который отправляется на endpoint при наступлении соответствующего события (используется для предварительной отладки кода обработки).

## Тестирование [#тестирование]

Для проверки корректности настройки эндпоинта доступны два инструмента:

### Пинг [#пинг]

Отправка простого запроса без полезной нагрузки для проверки доступности вашего сервера. По результату видно, отвечает ли эндпоинт и с каким HTTP-кодом.

### Тестовое событие [#тестовое-событие]

Отправка тестового события с примером данных (например, `verification.approved` с тестовым payload). Используется для проверки:

- Корректности маршрутизации запроса на вашей стороне.
- Правильности верификации подписи HMAC.
- Обработки структуры payload вашим приложением.

Результат тестовой отправки отображается в журнале доставок.