> ## 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. # Создание webhook-адреса назначения через API > Регистрируйте новый webhook-адрес назначения Didit с версией, подписанными событиями и секретом подписи. Управление webhook через API, оплата за вызов. Промпт API для создания адреса назначения webhook Скопировать промпт в буфер обмена \

\`Register a new webhook destination for my Didit application through the Management API.

Endpoint:
POST https://verification.didit.me/v3/webhook/destinations/

Authentication:
Use the x-api-key header with my Didit API key.

Goal:
\- Create a destination where Didit pushes the events I subscribe to. Each destination is an independent (URL, signing secret, payload version, event subscription) tuple.

Request body (application/json):
\{
"label": "Production session webhooks",        // required, human-readable
"url": "https://yourapp.com/webhooks/didit",   // required, HTTPS URL; must be unique among the application's destinations
"enabled": true,                                 // optional, default true
"webhook_version": "v3",                        // optional, "v1" | "v2" | "v3" — v3 is current/recommended
"subscribed_events": ["status.updated", "data.updated"]  // required, at least one supported event
}

Supported subscribed_events values (no wildcard):
\- status.updated, data.updated — KYC/KYB session lifecycle.
\- user.status.updated, user.data.updated — User entity changes.
\- business.status.updated, business.data.updated — Business entity changes.
\- activity.created — accepted and covered by Try Webhook, but not delivered for live traffic today.
\- transaction.created, transaction.status.updated — Transaction monitoring events.
\- travel_rule.status.updated — a Travel Rule exchange changed status.
\- workflow.compliance_changed — a published workflow's compliance status changed.
\- transaction_rule_suggestions.created — a rule suggestion run proposed new rule changes.
\- The full list, including the Investigator and Authentication families, is at /integration/webhooks#event-types.

Critical: capture secret_shared_key from the response and store it securely.
\- The response includes secret_shared_key — this is the HMAC signing secret used to compute X-Signature, X-Signature-V2, and X-Signature-Simple headers on every webhook delivered to this URL. Verify with X-Signature-V2; X-Signature-Simple is deprecated and authenticates the envelope only.
\- Store the secret from the create response. GET /v3/webhook/destinations/{destination_uuid}/ also returns it in full to your API key, but storing it on create avoids leaking it through follow-up reads.
\- The secret is unique per-destination.
\- The rest of the 201 body has the same shape as GET /v3/webhook/destinations/{destination_uuid}/: secret_last4, health_status "healthy", a summary with zero counts and null times, and created_by_email and created_by_name set to null for a destination created with an API key.

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

Signature verification quick-start (HMAC-SHA256 over the raw request body):
import hmac, hashlib
def verify(body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)

Always verify against the raw request body, not the parsed JSON. See /integration/webhooks for the full v3 signature scheme.

Failure modes:
\- 400: duplicate URL among the application's destinations, empty subscribed_events, unknown event name, or invalid URL.
\- 401 — missing or malformed x-api-key.
\- 403 — canonical { "detail": "You do not have permission to perform this action." } envelope.

Side effects:
\- A new destination is created and will start receiving deliveries for subscribed_events immediately (assuming enabled: true).
\- Not idempotent — repeated POSTs with different metadata create separate destinations.

For the full integration shape, see /integration/integration-prompt.`

\
Вставьте в Адреса назначения webhook позволяют отправлять разные события Didit на разные URL. У каждого адреса назначения есть собственные `secret_shared_key`, `webhook_version` и список `subscribed_events`.## Как работает `subscribed_events``subscribed_events` является обязательным массивом точных названий событий. Didit доставляет webhook на этот адрес назначения только тогда, когда `webhook_type` в payload совпадает с одним из значений в массиве.- Укажите хотя бы одно событие. - Используйте только поддерживаемые названия событий из списка ниже. - Добавьте каждое событие, которое хотите получать; подстановочного значения вроде `*` или `all` не существует. - Чтобы направлять разные продуктовые направления в разные системы, создайте несколько адресов назначения с разными списками `subscribed_events`.## Каталог событий| Событие | Подписывайтесь, если вам нужно это событие | | - | - | | `status.updated` | Изменяется статус сессии Проверки пользователей (KYC) или Верификации бизнеса (KYB). Payload для KYB содержит `session_kind: "business"` и `business_session_id`. | | `data.updated` | Данные верификации сессии исправлены или обновлены после создания, например при правках проверяющего в данных KYC, Подтверждения адреса или KYB. | | `user.status.updated` | Сущность User меняет статус, например на `ACTIVE`, `FLAGGED` или `BLOCKED`. | | `user.data.updated` | Меняются профиль сущности User, счётчики, метаданные, документы или агрегированные поля верификации. | | `business.status.updated` | Сущность Business меняет статус, например после ручной проверки, результатов KYB или действия по списку блокировки. | | `business.data.updated` | Меняются профиль сущности Business, счётчики, метаданные, регистрационные поля или агрегированные поля верификации. | | `activity.created` | Принимается в `subscribed_events` и поддерживается в **Try Webhook**, но Didit в настоящее время не отправляет его для боевого трафика. | | `transaction.created` | Создана транзакция, проходящая через Мониторинг транзакций, и завершена её первоначальная оценка по правилам. | | `transaction.status.updated` | Транзакция меняет статус после применения правил, проверки аналитиком, исправления, обновлений от провайдера или действий через API или консоль; также отправляется один раз, когда завершается криптоскрининг, повторённый в фоновом режиме. | | `travel_rule.status.updated` | Меняется статус обмена по [Travel Rule](https://docs.didit.me/ru/transaction-monitoring/travel-rule.md). | | `workflow.compliance_changed` | Меняется статус соответствия опубликованного сценария после повторной оценки. | | `transaction_rule_suggestions.created` | В результате запуска формирования предложений по правилам предлагаются новые изменения правил. |Семейства событий Investigator (`investigator.*`) и Authentication (`auth.*`) также принимаются. Все события и их payload перечислены в разделе [Webhooks](https://docs.didit.me/ru/integration/webhooks.md#типы-событий).Распространённые наборы подписок:```json theme={null} { "subscribed_events": ["status.updated", "data.updated"] } ``````json theme={null} { "subscribed_events": ["transaction.created", "transaction.status.updated"] } ``````json theme={null} { "subscribed_events": [ "user.status.updated", "user.data.updated", "business.status.updated", "business.data.updated", "activity.created" ] } ```Примеры payload и код для подписи см. в [руководстве по webhook](https://docs.didit.me/ru/integration/webhooks.md). ## OpenAPI ````yaml ru/openapi-25.json POST /v3/webhook/destinations/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: >- API верификации личности. Аутентификация выполняется с помощью заголовка x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/webhook/destinations/: post: tags: - Webhook summary: Создать адрес назначения webhook description: >- Создайте адрес назначения webhook. Ответ содержит автоматически сгенерированный секрет подписи HMAC `secret_shared_key` (также доступный позже через `GET /v3/webhook/destinations/{destination_uuid}/`). Обязательно передавайте `subscribed_events` хотя бы с одним событием (подстановочные символы не поддерживаются): пустой список отклоняется с кодом 400, а отсутствие поля создаёт адрес назначения без подписок, который никогда не получит webhook. Пара `(application, url)` должна быть уникальной среди адресов назначения приложения. operationId: create_webhook_destination requestBody: required: true content: application/json: schema: type: object required: - label - url properties: label: type: string maxLength: 255 description: >- Понятное имя, отображаемое в Console → Webhooks. Помогает различать адреса назначения, если их несколько (например, «Prod», «Staging mirror»). url: type: string format: uri description: >- HTTPS-URL, который будет принимать `POST`-запросы. Должен быть уникальным среди адресов назначения приложения. Используйте стабильный, защищённый endpoint: Didit выполняет повторные попытки неудавшейся доставки по схеме задержек между повторными попытками. maxLength: 2000 enabled: type: boolean default: true description: >- Если `false`, адрес назначения сохраняется, но Didit не отправляет на него никакие webhook. Полезно для staging-конфигураций, которые вы хотите оставить неактивными. webhook_version: type: string enum: - v1 - v2 - v3 description: >- Версия схемы payload, которую отправит Didit. `v3` является текущим и рекомендуемым форматом; более старые версии сохранены для обратной совместимости с устаревшими интеграциями. subscribed_events: allOf: - $ref: '#/components/schemas/WebhookSubscribedEvents' description: >- События для доставки. Фактически обязательно: явный массив `[]` отклоняется с кодом 400, а пропуск поля создаёт адрес назначения без подписок, который ничего не получает. examples: session_updates: summary: Обновления статуса и данных сессии value: label: Production session webhooks url: https://yourapp.com/webhooks/didit webhook_version: v3 subscribed_events: - status.updated - data.updated transaction_updates: summary: Обновления мониторинга транзакций value: label: Transaction monitoring webhooks url: https://yourapp.com/webhooks/didit-transactions webhook_version: v3 subscribed_events: - transaction.created - transaction.status.updated entity_updates: summary: Обновления сущностей пользователя и компании value: label: Entity lifecycle webhooks url: https://yourapp.com/webhooks/didit-entities webhook_version: v3 subscribed_events: - user.status.updated - user.data.updated - business.status.updated - business.data.updated - activity.created responses: '201': description: >- Адрес назначения создан. `secret_shared_key` — это секрет подписи HMAC, сохраните его сейчас. content: application/json: schema: type: object properties: uuid: type: string format: uuid description: >- Постоянный идентификатор назначения. Используйте как `{destination_uuid}` в последующих вызовах. label: type: string url: type: string format: uri enabled: type: boolean webhook_version: type: string enum: - v1 - v2 - v3 secret_shared_key: type: string description: >- Автоматически сгенерированный секрет подписи HMAC, привязанный к этому адресу назначения (URL-безопасный token из 43 символов). Используйте его для проверки заголовков подписи во входящих webhook. При запросе с API-ключом всегда возвращается полностью; пользователям Консоли требуется разрешение `read:webhooks`, иначе они увидят пустую строку. secret_last4: type: string description: >- Последние четыре символа текущего секрета подписи адреса назначения, позволяющие различать секреты. Недостаточно для проверки подписи. previous_secret_expires_at: type: string format: date-time nullable: true description: >- Устанавливается на 24 часа после ротации секрета подписи адреса назначения в Business Console. До истечения этого времени каждая доставка на адрес назначения также содержит `X-Signature-Previous`, `X-Signature-V2-Previous` и `X-Signature-Simple-Previous`, созданные с заменённым секретом (см. [Проверка подписи](/ru/integration/webhooks#проверка-подписи)). `null`, если за последние 24 часа ротация не проводилась. subscribed_events: $ref: '#/components/schemas/WebhookSubscribedEvents' created_by_email: type: string nullable: true description: >- Электронная почта участника Business Console, создавшего адрес назначения. `null` для адреса назначения, созданного с помощью API-ключа. created_by_name: type: string nullable: true description: >- Имя участника Business Console, создавшего адрес назначения. `null` для адреса назначения, созданного с помощью API-ключа. created_at: type: string format: date-time updated_at: type: string format: date-time health_status: type: string enum: - healthy - degraded - failing description: >- Состояние доставки. `failing`: 3 или более последовательных событий завершились неудачей при первой попытке доставки с момента последнего успешного ответа адреса назначения (см. `failing_streak`). `degraded`: не failing, но за последние 24 часа произошла неудачная попытка доставки, и ни одна последующая попытка пока не доставила это событие; повторная попытка или повторная отправка, которая доставит его, сбрасывает этот статус. `healthy`: ни то, ни другое. Не зависит от `enabled`. Неудачной считается попытка, получившая ответ HTTP 400 или выше, либо оставшаяся вовсе без ответа. failing_streak: type: integer description: >- Количество последовательных событий, первая попытка доставки которых завершилась неудачно с момента последнего успешного ответа адреса назначения за последние 30 дней. Повторные попытки не учитываются, и любая успешная попытка, включая повторную попытку или повторную отправку, прерывает серию. Значение равно `0`, если с момента последнего успеха не было ни одного сбоя. failing_since: type: string format: date-time nullable: true description: >- Когда была совершена первая неудачная попытка из текущей серии ошибок `failing_streak`. `null`, если `failing_streak` равен `0`. last_success_at: type: string format: date-time nullable: true description: >- Когда адрес назначения в последний раз ответил на доставку с HTTP-статусом ниже 400 за последние 30 дней. `null`, если ответов в этот период не было. environment: type: string enum: - live - sandbox description: Среда приложения, которому принадлежит адрес назначения. summary: type: object description: >- Метрики доставки за последние `metrics_window_days` (30) дней. `last_delivery_at` представляет собой самую последнюю попытку, когда бы она ни выполнялась. properties: total_deliveries: type: integer failed_deliveries: type: integer error_rate_percentage: type: integer min_response_time_ms: type: integer nullable: true avg_response_time_ms: type: integer nullable: true max_response_time_ms: type: integer nullable: true last_delivery_at: type: string format: date-time nullable: true metrics_window_days: type: integer description: >- Длина окна в днях, охватываемого остальными сводными метриками. Всегда `30`. examples: Created: value: uuid: 11111111-2222-3333-4444-555555555555 label: Production session webhooks url: https://yourapp.com/webhooks/didit enabled: true webhook_version: v3 secret_shared_key: tno2NTeRC1ZK3sBOYlBJDyEzBVENl3pQ1AcZyAW0xnQ secret_last4: 0xnQ previous_secret_expires_at: null subscribed_events: - status.updated - data.updated created_by_email: null created_by_name: null created_at: '2026-05-17T10:00:00Z' updated_at: '2026-05-17T10:00:00Z' health_status: healthy failing_streak: 0 failing_since: null last_success_at: null environment: live summary: total_deliveries: 0 failed_deliveries: 0 error_rate_percentage: 0 min_response_time_ms: null avg_response_time_ms: null max_response_time_ms: null last_delivery_at: null metrics_window_days: 30 '400': description: >- Ошибка валидации — обычно повторяющийся URL, отсутствующий/недопустимый `subscribed_events` или неизвестное имя события. content: application/json: examples: Duplicate URL: value: url: - >- This webhook destination already exists for the application. Empty events list: value: subscribed_events: - At least one subscribed event is required. Unknown event: value: subscribed_events: - 'Unsupported webhook events: foo.bar' '403': description: >- API-ключ отсутствует, сформирован некорректно, истёк или относится к другому приложению. При отсутствии ключа возвращается `403`; при неверном, отозванном или истёкшем ключе возвращается `401`. content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. '429': description: >- Лимит запросов превышен; снизьте частоту запросов и повторите попытку. content: application/json: examples: Throttled: value: detail: Request was throttled. Expected available in 30 seconds. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X POST 'https://verification.didit.me/v3/webhook/destinations/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "webhook_version": "v3", "subscribed_events": ["status.updated", "data.updated"] }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.webhooks.destinations.create( label="Production session webhooks", url="https://yourapp.com/webhooks/didit", webhook_version="v3", subscribed_events=["status.updated", "data.updated"], ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.webhooks.destinations.create({ label: "Production session webhooks", url: "https://yourapp.com/webhooks/didit", webhook_version: "v3", subscribed_events: ["status.updated", "data.updated"], }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.Create(ctx, didit.WebhooksDestinationsCreateParams{\n\tLabel: \"Production session webhooks\",\n\tURL: \"https://yourapp.com/webhooks/didit\",\n\tWebhookVersion: didit.Some(didit.WebhooksDestinationsCreateParamsWebhookVersion(\"v3\")),\n\tSubscribedEvents: didit.Some([]didit.WebhookEvent{didit.WebhookEvent(\"status.updated\"), didit.WebhookEvent(\"data.updated\")}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.util.List; import me.didit.Didit; import me.didit.types.WebhookEvent; import me.didit.types.WebhooksDestinationsCreateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.webhooks().destinations().create(WebhooksDestinationsCreateParams.builder() .label("Production session webhooks") .url("https://yourapp.com/webhooks/didit") .webhookVersion(WebhooksDestinationsCreateParams.WebhookVersion.of("v3")) .subscribedEvents(List.of(WebhookEvent.of("status.updated"), WebhookEvent.of("data.updated"))) .build()); System.out.println(result); - lang: php label: PHP source: |- webhooks->destinations->create([ 'label' => 'Production session webhooks', 'url' => 'https://yourapp.com/webhooks/didit', 'webhook_version' => 'v3', 'subscribed_events' => ['status.updated', 'data.updated'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.webhooks.destinations.create( label: "Production session webhooks", url: "https://yourapp.com/webhooks/didit", webhook_version: "v3", subscribed_events: ["status.updated", "data.updated"] ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Webhooks.Destinations.CreateAsync(new WebhooksDestinationsCreateParams { Label = "Production session webhooks", Url = "https://yourapp.com/webhooks/didit", WebhookVersion = new WebhooksDestinationsCreateParamsWebhookVersion("v3"), SubscribedEvents = new WebhookEvent[] { "status.updated", "data.updated" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: WebhookSubscribedEvents: type: array description: >- Фильтр событий для этого адреса назначения webhook. Didit доставляет только те webhook, чей тип события точно совпадает с одним из этих значений — подписка по маске отсутствует. При отправке список должен содержать как минимум одно допустимое событие (явный пустой массив `[]` отклоняется с кодом 400); адрес назначения с пустым списком (поле пропущено при создании) ничего не получает. При обновлении список заменяется целиком, а не объединяется. minItems: 1 uniqueItems: true items: $ref: '#/components/schemas/WebhookEvent' example: - status.updated - data.updated WebhookEvent: type: string description: >- Поддерживаемое имя события webhook. Используйте именно эти строки в `subscribed_events`; неподдерживаемые значения отклоняются. enum: - status.updated - data.updated - user.status.updated - user.data.updated - business.status.updated - business.data.updated - activity.created - transaction.created - transaction.status.updated - travel_rule.status.updated - workflow.compliance_changed - transaction_rule_suggestions.created - auth.signup - auth.login - auth.login_failed - auth.password_reset_requested - auth.password_reset_completed - auth.mfa_changed - auth.new_device - auth.account_locked - investigator.report.ready - investigator.decision.automated - investigator.decision.overridden - investigator.decision.contested - investigator.question.raised - investigator.automation.paused - investigator.rfi.answered - investigator.rfi.overdue - investigator.drift.detected - investigator.sla.breached - investigator.qa.failed - investigator.external.report.ready securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- API-ключ вашего приложения из раздела «Разработчикам» -> «API-ключи» в Business Console. Основной ключ имеет полный доступ. Именованный ключ может иметь ограниченную область действия: без доступа, чтение или запись для каждого ресурса, ограничение определенными сценариями или одобренными сессиями, списком IP-адресов и сроком действия. 401 означает, что ключ неверен, отозван или его срок действия истек; 403 означает, что ключ не был передан, у ключа нет доступа к этому ресурсу или действию, либо запрос поступил с адреса вне его списка IP-адресов; 404 на маршруте сессии означает, что сессия не входит в сценарии или статусы ключа. Ключ без доступа к медиа получает URL изображений, видео и PDF как null, а ключ без прав на запись сессий получает ссылки на сессии и токены как null. См. https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.