Получение результатов верификации через webhooks
Didit не отправляет email при изменении статуса верификации - настройте webhook, чтобы ваш бэкенд узнавал об этом в момент события, и проверяйте подпись перед тем, как доверять данным.
Webhook - это HTTP-запрос, который Didit отправляет на ваш URL при изменении. Добавьте назначение в разделе API & Webhooks, подпишитесь на нужные события - подстановочного знака нет, перечислите каждое - сохраните секрет подписи и проверяйте подпись, прежде чем что-либо обрабатывать.
Didit не отправляет вам email, когда сессия переходит в In Review или Declined. Чтобы узнавать об изменении статуса в момент, когда оно происходит, не обновляя консоль вручную, настройте webhook - URL на вашем сервере, на который Didit автоматически отправляет обновление.
Webhooks - это рекомендуемый способ интеграции. Опрос endpoint решений работает как запасной вариант, но он медленнее, требует больше запросов и пропускает события, которые доставляются только через webhook, - правки данных, внесённые ревьюером, изменения статуса транзакций и изменения на уровне сущностей.
#Настройка
- Перейдите в API & Webhooks
В Business Console откройте приложение, для которого хотите получать события, затем перейдите в API & Webhooks.
- Добавьте назначение
Задайте название, публичный HTTPS-URL вашего эндпоинта и выберите нужные события - как минимум изменения статуса сессии.
- Сохраните секрет подписи
Назначение показывает секрет один раз. Сохраните его - ваш сервер использует его, чтобы подтвердить, что запрос действительно пришёл от Didit, а не от кого-то, кто выдаёт себя за него. Полное описание проверки: проверка подписи.
- Проверьте настройку
Используйте Try Webhook на той же странице, чтобы отправить полностью сформированное тестовое событие - сценарии approved, declined, in review, KYB, entity и transaction - на ваш эндпоинт. Так можно проверить интеграцию без запуска настоящей верификации.
- Add destination регистрирует URL, на который Didit отправляет результаты.
- Проверяйте каждую доставку по этому секрету подписи, прежде чем ей доверять.
- Выберите, какие события будет получать назначение.
- Test Webhook отправляет пример payload, чтобы вы могли убедиться, что ваш эндпоинт его принимает.
#На какие события можно подписаться
Подстановочного знака нет - перечисляйте каждое нужное семейство событий. Разнести их по нескольким назначениям - это нормально и часто даже удобнее.
| Событие | Срабатывает, когда |
|---|---|
status.updated | Меняется статус сессии KYC или KYB. То, что вам почти наверняка нужно |
data.updated | Данные верификации редактируются после создания - например, ревьюер исправляет поле |
user.status.updated | Консолидированный пользователь переходит между ACTIVE, FLAGGED и BLOCKED |
user.data.updated | Меняется профиль, счётчики или идентификаторы консолидированного пользователя |
business.status.updated | Меняется статус консолидированной компании |
business.data.updated | Меняются данные консолидированной компании |
transaction.created | Транзакция создана, и по ней готов первоначальный вердикт |
transaction.status.updated | Статус транзакции меняется впоследствии |
travel_rule.status.updated | Меняется статус обмена по Travel Rule |
Событий session.status.updated или kyc.completed не существует. Если вы
подписались на название, которого нет в этом списке, вы не получите ничего - и
это будет выглядеть в точности как сбой доставки. Сначала проверьте название.
#Что должен делать ваш эндпоинт
- Проверять подпись раньше всего остального. Считайте HMAC от сырого тела запроса - никогда от пересериализованной версии разобранного JSON, потому что повторная сериализация меняет байты, и подпись перестаёт совпадать. Используйте сравнение за постоянное время.
- Быстро возвращать 2xx. Тяжёлую работу выполняйте асинхронно, уже после ответа.
- Быть идемпотентным. Ключом должен быть id события либо связка id сессии + статус + тип webhook. Повторы и дубликаты случаются.
- Обрабатывать каждый статус, который для вас важен, включая те, что приходят намного позже онбординга - одобренная сессия может позже перейти в In Review из-за постоянного AML-мониторинга.
- Только HTTPS. Обычные HTTP-эндпоинты не поддерживаются.
#Повторы
При 5xx, 404, таймауте или обрыве соединения Didit повторяет попытку дважды:
- Первый повтор примерно через 1 минуту после первоначального сбоя
- Второй повтор примерно через 4 минуты после этого
После этого доставка прекращается. Каждая попытка логируется отдельно во вкладке Deliveries назначения, поэтому вы можете увидеть, что именно произошло, а не гадать.
Два повтора за пять минут - это не надёжная очередь. Если ваш эндпоинт не работал час, эти события потеряны. Сверяйтесь при старте, опрашивая endpoint решений по сессиям, для которых у вас нет финального статуса - webhooks это быстрый путь, а не единственный.
#За файрволом или WAF
Didit доставляет события со статического IP 18.203.201.92 с user agent DiditWebhook/2.0. Если ваш периметр блокирует неизвестных клиентов - как, например, поведение Cloudflare по умолчанию, - разрешите этот IP для принимающего хоста, иначе доставки будут падать, не доходя до вашего кода.
#Ещё нет бэкенда?
Вы всё ещё можете вручную следить за результатами в разделе Verifications консоли, пока не построите его, или использовать ссылку для верификации без кода тем временем.
#Дальнейшие шаги
- Когда webhook так и не приходит: когда webhook так и не приходит
- Разобраться, что означает каждый статус после его получения: что означает каждый статус сессии
- Полная техническая документация, включая примеры кода для проверки подписи: Webhooks