KYB Webhooks

Business Verification and Business entities emit webhook events on every meaningful state change. Subscribe to the events you care about via the webhook destinations API or the Business Console.

Event catalog

Webhook events are shared between User and Business sessions — the session_kind field on the payload tells you which kind the event refers to. Entity-level events are separate from session-level events.

Session-level events

Event	When it fires
`status.updated`	A session’s status changed. For Business Verification (KYB) sessions the payload carries `session_kind: "business"`.
`data.updated`	A session’s data was updated (registry refresh, key-people submission, document upload, AML rescan). Payload includes `session_kind: "business"` for KYB sessions.

Business entity events

Event	When it fires
`business.status.updated`	The linked Business entity’s status changed (`ACTIVE` / `FLAGGED` / `BLOCKED`).
`business.data.updated`	The Business entity’s profile fields or aggregate counters changed.

Subscribe to any combination on your webhook destination. See entity webhooks for the full Business / User entity event reference.

Envelope

Every webhook uses the same top-level envelope. The session_kind field inside data discriminates between User Verification (KYC) and Business Verification (KYB) for session-level events.

{
  "event": "status.updated",
  "event_id": "evt_01H8X...",
  "application_id": "app_abc123",
  "timestamp": "2026-04-18T12:30:00Z",
  "data": { ... }
}

Payload shapes

`status.updated` — Business Verification (KYB) session

Fires when a KYB session’s status transitions.

{
  "event": "status.updated",
  "data": {
    "session_id": "bs_01H...",
    "session_kind": "business",
    "previous_status": "IN_PROGRESS",
    "status": "APPROVED",
    "vendor_data": "biz-acme-001",
    "workflow_id": "wf_kyb_standard",
    "features": ["KYB_REGISTRY", "KYB_COMPANY_AML", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE"],
    "decision": { ...abbreviated KYB decision payload... },
    "changed_at": "2026-04-18T12:30:00Z"
  }
}

The decision block contains the same shape as GET /v3/session/{id}/decision/ — registry_checks[], key_people_checks[], document_verifications[], aml_screenings[], etc.

`data.updated` — Business Verification (KYB) session

Fires when session data (registry, key people, documents, AML) changed without a status transition.

{
  "event": "data.updated",
  "data": {
    "session_id": "bs_01H...",
    "session_kind": "business",
    "vendor_data": "biz-acme-001",
    "changed_fields": ["registry_checks", "key_people_checks"],
    "updated_at": "2026-04-18T14:00:00Z"
  }
}

Use changed_fields to efficiently decide what to re-fetch.

`business.status.updated`

Fires when the Business entity moves between ACTIVE, FLAGGED, or BLOCKED.

{
  "event": "business.status.updated",
  "data": {
    "vendor_data": "biz-acme-001",
    "uuid": "f7a9c1b2-4e6d-4f8a-9c5d-2a1b3c4d5e6f",
    "status": "FLAGGED",
    "previous_status": "ACTIVE",
    "reason": "manual",
    "actor": "compliance@yourcorp.com"
  }
}

`business.data.updated`

Fires when the Business entity’s profile fields or aggregate counters change.

{
  "event": "business.data.updated",
  "data": {
    "vendor_data": "biz-acme-001",
    "uuid": "...",
    "legal_name": "Acme Corporation Limited",
    "registration_number": "12345678",
    "country_code": "GBR",
    "session_count": 2,
    "approved_count": 1,
    "declined_count": 0,
    "in_review_count": 1,
    "changed_fields": ["session_count", "approved_count", "features"]
  }
}

Signature verification

All webhooks are signed HMAC-SHA256 with your destination’s shared secret, sent in the X-Didit-Signature header. Verify the raw request body before acting. Example (Node.js):

import { createHmac, timingSafeEqual } from 'crypto';

function verifyWebhook(rawBody: string, signature: string, secret: string): boolean {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
  const provided = Buffer.from(signature);
  const computed = Buffer.from(expected);
  return provided.length === computed.length && timingSafeEqual(provided, computed);
}

Full details in the webhooks reference.

Retry policy

Non-2xx responses trigger retries with exponential backoff.
Up to 5 retries over ~24 hours.
Each retry gets a new X-Didit-Delivery header but the same event_id — de-duplicate on your side.
Repeated failures flip the destination to disabled.

Subscribing

Subscribe to the events you care about on a webhook destination:

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",
      "activity.created"
    ]
  }'

Filter for business sessions on your side by checking data.session_kind === "business" inside status.updated and data.updated events.

Next steps

Webhooks reference

Destinations, signing, retries, common patterns.

Statuses

Session and feature status reference.

Response schema

Decoding the KYB decision payload.

Getting Started

Features

Business Profiles

Reference

Console

Event catalog

Session-level events

Business entity events

Envelope

Payload shapes

`status.updated` — Business Verification (KYB) session

`data.updated` — Business Verification (KYB) session

`business.status.updated`

`business.data.updated`

Signature verification

Retry policy

Subscribing

Next steps

Webhooks reference

Statuses

Response schema

​Event catalog

​Session-level events

​Business entity events

​Envelope

​Payload shapes

​status.updated — Business Verification (KYB) session

​data.updated — Business Verification (KYB) session

​business.status.updated

​business.data.updated

​Signature verification

​Retry policy

​Subscribing

​Next steps

Webhooks reference

Statuses

Response schema

Event catalog

Session-level events

Business entity events

Envelope

Payload shapes

`status.updated` — Business Verification (KYB) session

`data.updated` — Business Verification (KYB) session

`business.status.updated`

`business.data.updated`

Signature verification

Retry policy

Subscribing

Next steps