> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> События KYB webhook для сессий и компаний в Didit: триггеры, схемы payload и проверка подписи HMAC. От $2.00 за проверку, без контрактов.

Didit's KYB webhooks сообщают вашему бэкенду, когда сессия верификации бизнеса меняет статус или когда проверяющий либо реестр меняет данные.
У сущностей Business есть собственные события.
Подпишитесь на нужные события через [API адресов назначения webhook](https://docs.didit.me/ru/management-api/webhook/list-destinations.md) или в Business Console.

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

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

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

| Событие | Когда отправляется |
| - | - |
| `status.updated` | Статус сессии изменился. Для сессий «Верификация бизнеса (KYB)» payload содержит `session_kind: "business"`. Это основное событие для отслеживания прогресса. |
| `data.updated` | Проверяющий изменил данные реестра, пропустил или пересоздал Key People в консоли либо реестр сообщил об изменении (когда доступен [мониторинг реестра](https://docs.didit.me/ru/getting-started/kyb-registry-pricing.md)). Поле `trigger` показывает, какое из этих действий произошло. |

`data.updated` не отправляется, когда заявитель загружает документ или отправляет Key People, а также когда завершается повторный AML-скрининг.
Чтобы отслеживать этот прогресс, используйте `status.updated` или [получите решение по сессии](https://docs.didit.me/ru/sessions-api/retrieve-session.md).

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

| Событие | Когда отправляется |
| - | - |
| `business.status.updated` | Статус связанной [сущности Business](https://docs.didit.me/ru/entities/businesses/overview.md) изменился (`ACTIVE` / `FLAGGED` / `BLOCKED`). |
| `business.data.updated` | Поля профиля сущности Business или агрегированные счётчики изменились. |

Подпишитесь на любую комбинацию этих событий на вашем адресе назначения webhook.
Полный справочник событий сущностей Business и User см. в разделе [webhook для сущностей](https://docs.didit.me/ru/entities/webhooks.md).

## Структура payload

Webhook сессий использует плоский payload без обёртки `data`.
Оболочка, заголовки подписи и все общие поля описаны в [справочнике по webhook](https://docs.didit.me/ru/integration/webhooks.md#структура-payload).
Сессия KYB добавляет следующие поля:

| Поле | Тип | Описание |
| - | - | - |
| `session_kind` | `"business"` | Позволяет универсальному обработчику разделять KYC и KYB. |
| `business_session_id` | `uuid` | Совпадает с `session_id`. |
| `vendor_business_id` | строка | Ваш идентификатор сущности Business, если он передан при создании сессии. |
| `status` | строка | Точная метка статуса, например `"In Progress"`, `"Approved"` или `"Awaiting User"`. См. [статусы](https://docs.didit.me/ru/business-verification/statuses.md). |
| `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/`](https://docs.didit.me/ru/sessions-api/retrieve-session), см. [схему ответа](https://docs.didit.me/ru/business-verification/response-schema.md). |
| `resubmit_info` | объект | Присутствует, когда `status` равен `Resubmitted`. |

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

```json theme={null}
{
  "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 } }`.

```json theme={null}
{
  "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](https://docs.didit.me/ru/integration/webhooks.md#проверка-подписи) перечислены все заголовки подписи, период перекрытия при смене секрета подписи и примеры кода.

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

* Ответ `5xx` или `404`, таймаут либо ошибка соединения запускают до 2 повторных попыток: примерно через 1 минуту и примерно через 4 минуты. После этого доставка отбрасывается.
* Ответы `4xx` (кроме перечисленных) и `3xx` не повторяются.
* Каждая повторная попытка сохраняет тот же `event_id`, поэтому отсеивайте дубликаты по нему.
* Вы можете переотправить доставку из журнала доставок адреса назначения. Полная политика описана в [справочнике по webhook](https://docs.didit.me/ru/integration/webhooks.md#политика-повторных-попыток).

## Подписка

Подпишитесь на нужные события на [адресе назначения webhook](https://docs.didit.me/ru/management-api/webhook/create-destination.md):

```bash theme={null}
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`.

## Что дальше

> [card] [Справочник по webhook](https://docs.didit.me/ru/integration/webhooks.md)
>
> Адреса назначения, подпись, повторные попытки, типовые сценарии.

> [card] [Статусы](https://docs.didit.me/ru/business-verification/statuses.md)
>
> Справочник статусов сессий и функций.

> [card] [Схема ответа](https://docs.didit.me/ru/business-verification/response-schema.md)
>
> Разбор payload решения KYB.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.