Вебхуки
Раздел Вебхуки предназначен для настройки уведомлений о событиях верификации. OneKYC отправляет HTTP-запросы на указанные вами URL-адреса при наступлении определённых событий (создание сессии, завершение шага, одобрение или отклонение верификации и другие).
Эндпоинты
Эндпоинт — это URL-адрес вашего сервера, на который OneKYC направляет уведомления. Допускается создание нескольких эндпоинтов для различных целей и окружений.
Создание эндпоинта
При создании нового эндпоинта укажите следующие параметры:
- URL — адрес вашего сервера для приёма уведомлений. Обязательно использование протокола HTTPS.
- Описание — пояснение назначения эндпоинта (например, «Production CRM», «Аналитическая система»).
- Окружение — sandbox или production. Определяет, события какого окружения будут направляться на данный URL.
- Типы событий — перечень событий, уведомления о которых необходимо получать:
- Все события (
*) — уведомления обо всех типах событий. - Выборочные события — индивидуальный набор (например,
verification.approved,verification.declined,step.completed). - KYB-события — события, связанные с верификацией юридических лиц (например,
kyb.business.verified), доступны в отдельной категории.
- Все события (
Полный перечень типов событий приведён в разделах: Вебхуки API, KYB Вебхуки.
Секрет подписи
После создания эндпоинта система генерирует секрет подписи с префиксом whsec_. Секрет используется для верификации подлинности входящих запросов на вашей стороне.
Секрет отображается однократно при создании. Сохраните его в защищённом хранилище немедленно.
Ротация секрета
При необходимости обновления секрета (плановая ротация или подозрение на компрометацию):
- Откройте карточку эндпоинта.
- Инициируйте ротацию секрета.
- В течение периода грации оба секрета (старый и новый) принимаются системой одновременно, что позволяет обновить код проверки подписи на вашей стороне без потери уведомлений.
- По истечении периода грации старый секрет прекращает действие.
Журнал доставок
В подразделе «Логи» (или «Deliveries») отображается история отправки уведомлений:
| Поле | Описание |
|---|---|
| Время | Дата и время отправки |
| URL | Адрес эндпоинта |
| Событие | Тип отправленного события |
| Статус ответа | HTTP-код ответа вашего сервера (2xx — успех, иное — ошибка) |
| Попытки | Количество попыток доставки |
При открытии детальной информации о доставке доступны: тело запроса, заголовки и ответ вашего сервера. Это позволяет диагностировать проблемы с приёмом уведомлений и проверкой подписи.
Повторная отправка
Для конкретной доставки, завершившейся ошибкой, доступна функция «Повторить отправку» (Resend) — уведомление будет направлено повторно на тот же эндпоинт.
Политика повторных попыток
При неуспешной доставке (ваш сервер не ответил или вернул код ошибки) OneKYC выполняет автоматические повторные попытки:
- Максимальное количество попыток — до 5.
- Стратегия — экспоненциальный backoff: базовая задержка 5 секунд, удваивается на каждой попытке, верхний предел 24 часа. Дополнительно применяется случайный jitter ±20 % для размазывания нагрузки.
- При исчерпании всех попыток событие помещается в очередь недоставленных сообщений (Dead Letter Queue) — см. ниже.
Очередь недоставленных сообщений (Dead Letter Queue)
В подразделе Dead Letter Queue доступны события, для которых исчерпаны все автоматические попытки доставки. Возможные действия:
- Повторная отправка отдельного события (
Retry) — уведомление направляется повторно на тот же эндпоинт. - Массовый retry (
Retry all) — повторная отправка всех событий из DLQ для выбранного эндпоинта (обычно используется после восстановления работоспособности приёмника). - Удаление события (
Delete) — событие исключается из DLQ без отправки.
Все массовые действия и retry фиксируются в журнале аудита.
Статистика и примеры payload
- Статистика доставок — сводные показатели по эндпоинту (количество отправок, успешных доставок, ошибок, среднее время ответа).
- Пример payload для каждого типа события — показывает структуру тела запроса, который отправляется на endpoint при наступлении соответствующего события (используется для предварительной отладки кода обработки).
Тестирование
Для проверки корректности настройки эндпоинта доступны два инструмента:
Пинг
Отправка простого запроса без полезной нагрузки для проверки доступности вашего сервера. По результату видно, отвечает ли эндпоинт и с каким HTTP-кодом.
Тестовое событие
Отправка тестового события с примером данных (например, verification.approved с тестовым payload). Используется для проверки:
- Корректности маршрутизации запроса на вашей стороне.
- Правильности верификации подписи HMAC.
- Обработки структуры payload вашим приложением.
Результат тестовой отправки отображается в журнале доставок.