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"]
  }'

import os

import requests

resp = requests.post(
    'https://verification.didit.me/v3/webhook/destinations/',
    headers={
        'x-api-key': os.environ['DIDIT_API_KEY'],
        'Content-Type': 'application/json',
    },
    json={
        'label': 'Production session webhooks',
        'url': 'https://yourapp.com/webhooks/didit',
        'webhook_version': 'v3',
        'subscribed_events': ['status.updated', 'data.updated'],
    },
    timeout=10,
)
resp.raise_for_status()
destination = resp.json()
# Store secret_shared_key in your secret manager.
print('Destination UUID:', destination['uuid'])
print('Signing secret:', destination['secret_shared_key'])

const resp = await fetch('https://verification.didit.me/v3/webhook/destinations/', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.DIDIT_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    label: 'Production session webhooks',
    url: 'https://yourapp.com/webhooks/didit',
    webhook_version: 'v3',
    subscribed_events: ['status.updated', 'data.updated'],
  }),
});
if (!resp.ok) throw new Error(await resp.text());
const destination = await resp.json();
console.log('Store this secret securely:', destination.secret_shared_key);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://verification.didit.me/v3/webhook/destinations/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'label' => 'Production session webhooks',
    'url' => 'https://yourapp.com/webhooks/didit',
    'webhook_version' => 'v3',
    'subscribed_events' => [
        'status.updated',
        'data.updated'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://verification.didit.me/v3/webhook/destinations/"

	payload := strings.NewReader("{\n  \"label\": \"Production session webhooks\",\n  \"url\": \"https://yourapp.com/webhooks/didit\",\n  \"webhook_version\": \"v3\",\n  \"subscribed_events\": [\n    \"status.updated\",\n    \"data.updated\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://verification.didit.me/v3/webhook/destinations/")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"label\": \"Production session webhooks\",\n  \"url\": \"https://yourapp.com/webhooks/didit\",\n  \"webhook_version\": \"v3\",\n  \"subscribed_events\": [\n    \"status.updated\",\n    \"data.updated\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://verification.didit.me/v3/webhook/destinations/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"label\": \"Production session webhooks\",\n  \"url\": \"https://yourapp.com/webhooks/didit\",\n  \"webhook_version\": \"v3\",\n  \"subscribed_events\": [\n    \"status.updated\",\n    \"data.updated\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "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

Create Webhook Destination

Create a webhook destination. The response includes the auto-generated secret_shared_key HMAC signing secret (also readable later via GET /v3/webhook/destinations/{destination_uuid}/). Always send subscribed_events with at least one event (no wildcards): an explicit empty list is rejected with 400, and omitting the field creates a destination subscribed to nothing, which never receives a webhook. The (application, url) pair must be unique among non-deleted destinations.

POST

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"]
  }'

import os

import requests

resp = requests.post(
    'https://verification.didit.me/v3/webhook/destinations/',
    headers={
        'x-api-key': os.environ['DIDIT_API_KEY'],
        'Content-Type': 'application/json',
    },
    json={
        'label': 'Production session webhooks',
        'url': 'https://yourapp.com/webhooks/didit',
        'webhook_version': 'v3',
        'subscribed_events': ['status.updated', 'data.updated'],
    },
    timeout=10,
)
resp.raise_for_status()
destination = resp.json()
# Store secret_shared_key in your secret manager.
print('Destination UUID:', destination['uuid'])
print('Signing secret:', destination['secret_shared_key'])

const resp = await fetch('https://verification.didit.me/v3/webhook/destinations/', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.DIDIT_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    label: 'Production session webhooks',
    url: 'https://yourapp.com/webhooks/didit',
    webhook_version: 'v3',
    subscribed_events: ['status.updated', 'data.updated'],
  }),
});
if (!resp.ok) throw new Error(await resp.text());
const destination = await resp.json();
console.log('Store this secret securely:', destination.secret_shared_key);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://verification.didit.me/v3/webhook/destinations/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'label' => 'Production session webhooks',
    'url' => 'https://yourapp.com/webhooks/didit',
    'webhook_version' => 'v3',
    'subscribed_events' => [
        'status.updated',
        'data.updated'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://verification.didit.me/v3/webhook/destinations/"

	payload := strings.NewReader("{\n  \"label\": \"Production session webhooks\",\n  \"url\": \"https://yourapp.com/webhooks/didit\",\n  \"webhook_version\": \"v3\",\n  \"subscribed_events\": [\n    \"status.updated\",\n    \"data.updated\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://verification.didit.me/v3/webhook/destinations/")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"label\": \"Production session webhooks\",\n  \"url\": \"https://yourapp.com/webhooks/didit\",\n  \"webhook_version\": \"v3\",\n  \"subscribed_events\": [\n    \"status.updated\",\n    \"data.updated\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://verification.didit.me/v3/webhook/destinations/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"label\": \"Production session webhooks\",\n  \"url\": \"https://yourapp.com/webhooks/didit\",\n  \"webhook_version\": \"v3\",\n  \"subscribed_events\": [\n    \"status.updated\",\n    \"data.updated\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "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

Event	Subscribe when you need
`status.updated`	User Verification (KYC) or Business Verification (KYB) session status changes. KYB payloads include `session_kind: "business"` and `business_session_id`.
`data.updated`	Session verification data is corrected or updated after creation, such as reviewer edits to KYC, Proof of Address, or KYB data.
`user.status.updated`	A User entity changes status, for example `ACTIVE`, `FLAGGED`, or `BLOCKED`.
`user.data.updated`	A User entity profile, counters, metadata, documents, or aggregate verification fields change.
`business.status.updated`	A Business entity changes status, for example after manual review, KYB results, or a blocklist action.
`business.data.updated`	A Business entity profile, counters, metadata, registration fields, or aggregate verification fields change.
`activity.created`	A timeline activity is recorded for a User, Business, external counterparty, session, or transaction.
`transaction.created`	A Transaction Monitoring transaction is created and its initial rule evaluation is complete.
`transaction.status.updated`	A 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,

travel_rule.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,

travel_rule.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).

Show child attributes

⌘I

Overview

User and Business Verifications

Lists

Workflows

Questionnaires

Users

Businesses

Cases

Case Blueprints

Report Templates

Regulatory Reports

Transactions

Travel Rule

Session Operations

Customization

Webhook

Billing

Management API Overview

Auth API (Programmatic)

Identity & Documents

Database Validation

Biometrics & Face

Compliance & Risk

Email Verification

Phone Verification

Create Webhook Destination

How `subscribed_events` works

Event catalog

Authorizations

Body

Response

​How subscribed_events works

​Event catalog

Authorizations

Body

Response

How `subscribed_events` works

Event catalog