Skip to main content
POST
/
v3
/
webhook
/
destinations
/
curl
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"]
  }'
{
  "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",
  "subscribed_events": [
    "status.updated",
    "data.updated"
  ],
  "created_at": "2026-05-17T10:00:00Z",
  "updated_at": "2026-05-17T10:00:00Z",
  "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
  }
}
Webhook destinations let you send different Didit events to different URLs. Each destination has its own secret_shared_key, webhook_version, and subscribed_events list.

​
How subscribed_events works

subscribed_events is a required array of exact event names. Didit delivers a webhook to this destination only when the payload’s webhook_type matches one of the values in the array.
  • Include at least one event.
  • Use only the supported event names below.
  • Add every event you want delivered; there is no wildcard value like * or all.
  • To route different product areas to different systems, create multiple destinations with different subscribed_events lists.

​
Event catalog

EventSubscribe when you need
status.updatedUser Verification (KYC) or Business Verification (KYB) session status changes. KYB payloads include session_kind: "business" and business_session_id.
data.updatedSession verification data is corrected or updated after creation, such as reviewer edits to KYC, Proof of Address, or KYB data.
user.status.updatedA User entity changes status, for example ACTIVE, FLAGGED, or BLOCKED.
user.data.updatedA User entity profile, counters, metadata, documents, or aggregate verification fields change.
business.status.updatedA Business entity changes status, for example after manual review, KYB results, or a blocklist action.
business.data.updatedA Business entity profile, counters, metadata, registration fields, or aggregate verification fields change.
activity.createdA timeline activity is recorded for a User, Business, external counterparty, session, or transaction.
transaction.createdA Transaction Monitoring transaction is created and its initial rule evaluation is complete.
transaction.status.updatedA transaction changes status after rules, analyst review, remediation, provider updates, or API/console actions.
Common subscription sets: 
{
  "subscribed_events": ["status.updated", "data.updated"]
}

{
  "subscribed_events": ["transaction.created", "transaction.status.updated"]
}

{
  "subscribed_events": [
    "user.status.updated",
    "user.data.updated",
    "business.status.updated",
    "business.data.updated",
    "activity.created"
  ]
}
For payload examples and signing code, see the webhooks guide.

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
label
string
required

Human-readable name displayed in Console → Webhooks. Helps distinguish destinations when you have several (e.g. "Prod", "Staging mirror").

Maximum string length: 255
​
url
string<uri>
required

HTTPS URL that will receive POST requests. Must be unique per application among non-deleted destinations. Use a stable, hardened endpoint — Didit retries failed deliveries on a backoff schedule.

​
enabled
boolean
default:true

When false, the destination is saved but Didit will not push any webhooks to it. Useful for staging configs you want to keep parked.

​
webhook_version
enum<string>

Payload schema version Didit will send. v3 is the current/recommended format; older versions are kept for backward compatibility with legacy integrations.

Available options:
v1,
v2,
v3
​
subscribed_events
enum<string>[]

Events to deliver. Effectively required: an explicit [] is rejected with 400, and omitting the field creates a destination with no subscriptions that receives nothing.

Minimum array length: 1

Supported webhook event name. Use these exact strings in subscribed_events; unsupported values are rejected.

Available options:
status.updated,
data.updated,
user.status.updated,
user.data.updated,
business.status.updated,
business.data.updated,
activity.created,
transaction.created,
transaction.status.updated
Example:
["status.updated", "data.updated"]

Response

Destination created. secret_shared_key is the HMAC signing secret — store it now.

​
uuid
string<uuid>

Stable destination identifier. Use as {destination_uuid} in subsequent calls.

​
label
string
​
url
string<uri>
​
enabled
boolean
​
webhook_version
enum<string>
Available options:
v1,
v2,
v3
​
secret_shared_key
string

Auto-generated HMAC signing secret bound to this destination (43-character URL-safe token). Use it to verify the signature headers on incoming webhooks. Always returned in full to API-key callers; Console users need the read:webhooks permission, otherwise they see an empty string.

​
subscribed_events
enum<string>[]

Event filter for this webhook destination. Didit delivers only webhooks whose event type exactly matches one of these values — there is no wildcard subscription. When sent, the list must contain at least one valid event (an explicit [] is rejected with 400); a destination whose list is empty (field omitted at create) receives nothing. On update the list is replaced wholesale, never merged.

Minimum array length: 1

Supported webhook event name. Use these exact strings in subscribed_events; unsupported values are rejected.

Available options:
status.updated,
data.updated,
user.status.updated,
user.data.updated,
business.status.updated,
business.data.updated,
activity.created,
transaction.created,
transaction.status.updated
Example:
["status.updated", "data.updated"]
​
created_at
string<date-time>
​
updated_at
string<date-time>
​
summary
object

Delivery health summary (all zero/null on a brand-new destination).