Webhooks KYB: события, payload и подпись HMAC

Didit’s KYB webhooks сообщают вашему бэкенду, когда сессия верификации бизнеса меняет статус или когда проверяющий либо реестр меняет данные. У сущностей Business есть собственные события. Подпишитесь на нужные события через API адресов назначения webhook или в Business Console.

Каталог событий

События сессий общие для сессий User и Business. Поле session_kind в payload показывает, к какому типу сессии относится событие. События на уровне сущности отделены от событий на уровне сессии.

События на уровне сессии

Событие	Когда отправляется
`status.updated`	Статус сессии изменился. Для сессий «Верификация бизнеса (KYB)» payload содержит `session_kind: "business"`. Это основное событие для отслеживания прогресса.
`data.updated`	Проверяющий изменил данные реестра, пропустил или пересоздал Key People в консоли либо реестр сообщил об изменении (когда доступен мониторинг реестра). Поле `trigger` показывает, какое из этих действий произошло.

data.updated не отправляется, когда заявитель загружает документ или отправляет Key People, а также когда завершается повторный AML-скрининг. Чтобы отслеживать этот прогресс, используйте status.updated или получите решение по сессии.

События сущности Business

Событие	Когда отправляется
`business.status.updated`	Статус связанной сущности Business изменился (`ACTIVE` / `FLAGGED` / `BLOCKED`).
`business.data.updated`	Поля профиля сущности Business или агрегированные счётчики изменились.

Подпишитесь на любую комбинацию этих событий на вашем адресе назначения webhook. Полный справочник событий сущностей Business и User см. в разделе webhook для сущностей.

Структура payload

Webhook сессий использует плоский payload без обёртки data. Оболочка, заголовки подписи и все общие поля описаны в справочнике по webhook. Сессия KYB добавляет следующие поля:

Поле	Тип	Описание
`session_kind`	`"business"`	Позволяет универсальному обработчику разделять KYC и KYB.
`business_session_id`	`uuid`	Совпадает с `session_id`.
`vendor_business_id`	строка	Ваш идентификатор сущности Business, если он передан при создании сессии.
`status`	строка	Точная метка статуса, например `"In Progress"`, `"Approved"` или `"Awaiting User"`. См. статусы.
`trigger`	строка	Необязательное поле. Причина отправки webhook. Для `data.updated` в KYB это `"console_registry_edit"`, `"console_key_people_skip"`, `"console_key_people_regenerate"` или `"kyb_registry_change"`.
`decision`	объект	Присутствует, когда `status` равен `Approved`, `Declined`, `In Review` или `Abandoned`. Имеет ту же структуру, что и `GET /v3/session/{id}/decision/`, см. схему ответа.
`resubmit_info`	объект	Присутствует, когда `status` равен `Resubmitted`.

`status.updated` для сессии KYB

{
  "event_id": "7f3c2c1e-6a1d-4c36-9d8e-0d3b5f4e2a10",
  "webhook_type": "status.updated",
  "session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "business_session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "session_kind": "business",
  "status": "Approved",
  "created_at": 1776515400,
  "timestamp": 1776515401,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "workflow_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
  "workflow_version": 3,
  "vendor_data": "biz-acme-001",
  "decision": { "...": "abbreviated KYB decision payload" }
}

Блок decision содержит registry_checks[], key_people_checks[], document_verifications[], aml_screenings[] и другие массивы KYB.

`data.updated` для сессии KYB

data.updated содержит ту же плоскую оболочку, что и status.updated, а также trigger, который показывает, почему событие было отправлено. Когда статус сессии равен Approved, Declined, In Review или Abandoned, событие также содержит текущий decision. Чтобы увидеть, что изменилось, повторно запросите решение. Списка changed_fields в payload нет.

`business.status.updated` и `business.data.updated`

События сущностей тоже плоские. Они содержат vendor_business_id, vendor_data, status (ACTIVE, FLAGGED или BLOCKED) и created_at. business.status.updated дополнительно содержит previous_status. business.data.updated дополнительно содержит changed_fields и карту changes вида { field: { previous, current } }.

{
  "event_id": "2b9d6f0a-3c41-4e8b-b6a7-5d1e8f9a0c32",
  "webhook_type": "business.status.updated",
  "timestamp": 1776515401,
  "created_at": 1776515400,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "vendor_business_id": "f7a9c1b2-4e6d-4f8a-9c5d-2a1b3c4d5e6f",
  "vendor_data": "biz-acme-001",
  "status": "FLAGGED",
  "previous_status": "ACTIVE"
}

Проверка подписи

Каждый webhook подписывается по HMAC-SHA256 с использованием общего секрета вашего адреса назначения. Проверяйте необработанное тело запроса по заголовку X-Signature-V2 (рекомендуется) и отклоняйте доставки, у которых X-Timestamp старше 300 секунд. В справочнике по webhook перечислены все заголовки подписи, период перекрытия при смене секрета подписи и примеры кода.

Политика повторных попыток

Ответ 5xx или 404, таймаут либо ошибка соединения запускают до 2 повторных попыток: примерно через 1 минуту и примерно через 4 минуты. После этого доставка отбрасывается.
Ответы 4xx (кроме перечисленных) и 3xx не повторяются.
Каждая повторная попытка сохраняет тот же event_id, поэтому отсеивайте дубликаты по нему.
Вы можете переотправить доставку из журнала доставок адреса назначения. Полная политика описана в справочнике по webhook.

curl -X POST https://verification.didit.me/v3/webhook/destinations/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "KYB events",
    "url": "https://yourapp.com/webhooks/didit-kyb",
    "subscribed_events": [
      "status.updated",
      "data.updated",
      "business.status.updated",
      "business.data.updated"
    ]
  }'

Чтобы отфильтровать сессии бизнеса на своей стороне, проверяйте session_kind === "business" в событиях status.updated и data.updated.

Что дальше

Справочник по webhook

Адреса назначения, подпись, повторные попытки, типовые сценарии.

Статусы

Справочник статусов сессий и функций.

Схема ответа

Разбор payload решения KYB.

Начало работы

Функции

Профили компаний

Справочник

Консоль

Webhooks KYB: события, payload и подпись HMAC

Каталог событий

События на уровне сессии

События сущности Business

Структура payload

`status.updated` для сессии KYB

`data.updated` для сессии KYB

`business.status.updated` и `business.data.updated`

Проверка подписи

Политика повторных попыток

Подписка

Что дальше

Справочник по webhook

Статусы

Схема ответа

​Каталог событий

​События на уровне сессии

​События сущности Business

​Структура payload

​status.updated для сессии KYB

​data.updated для сессии KYB

​business.status.updated и business.data.updated

​Проверка подписи

​Политика повторных попыток

​Подписка

​Что дальше

Справочник по webhook

Статусы

Схема ответа

Каталог событий

События на уровне сессии

События сущности Business

Структура payload

`status.updated` для сессии KYB

`data.updated` для сессии KYB

`business.status.updated` и `business.data.updated`

Проверка подписи

Политика повторных попыток

Подписка

Что дальше