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"]
}'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)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);ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()
result, err := client.Webhooks.Destinations.Create(ctx, didit.WebhooksDestinationsCreateParams{
Label: "Production session webhooks",
URL: "https://yourapp.com/webhooks/didit",
WebhookVersion: didit.Some(didit.WebhooksDestinationsCreateParamsWebhookVersion("v3")),
SubscribedEvents: didit.Some([]didit.WebhookEvent{didit.WebhookEvent("status.updated"), didit.WebhookEvent("data.updated")}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)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);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
// Reads DIDIT_API_KEY.
$didit = new DiditClient();
$result = $didit->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());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_husing 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));{
"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
}
}创建 Webhook 目标 API
在 Didit 中注册新的 Webhook 目标,配置版本、订阅事件和目标专属签名密钥。可编程管理 Webhook,按次计费。
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"]
}'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)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);ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()
result, err := client.Webhooks.Destinations.Create(ctx, didit.WebhooksDestinationsCreateParams{
Label: "Production session webhooks",
URL: "https://yourapp.com/webhooks/didit",
WebhookVersion: didit.Some(didit.WebhooksDestinationsCreateParamsWebhookVersion("v3")),
SubscribedEvents: didit.Some([]didit.WebhookEvent{didit.WebhookEvent("status.updated"), didit.WebhookEvent("data.updated")}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)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);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
// Reads DIDIT_API_KEY.
$didit = new DiditClient();
$result = $didit->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());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_husing 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));{
"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
}
}secret_shared_key、webhook_version 和 subscribed_events 列表。
subscribed_events 的工作方式
subscribed_events 是必填的精确事件名称数组。仅当 payload 中的 webhook_type 与数组中的某个值匹配时,Didit 才会将 Webhook 投递到此目标。
- 至少包含一个事件。
- 仅使用下方列出的受支持事件名称。
- 请添加您希望投递的每个事件;没有
*或all这样的通配符值。 - 若要将不同的产品领域路由到不同的系统,请使用不同的
subscribed_events列表创建多个目标。
事件目录
| 事件 | 需要订阅的情况 |
|---|---|
status.updated | 用户验证(KYC)或企业验证(KYB)会话的状态发生变化时。KYB payload 包含 session_kind: "business" 和 business_session_id。 |
data.updated | 会话验证数据在创建后被更正或更新时,例如审核员对 KYC、地址证明或 KYB 数据进行编辑。 |
user.status.updated | 用户实体的状态发生变化,例如 ACTIVE、FLAGGED 或 BLOCKED。 |
user.data.updated | 用户实体的资料、计数器、元数据、证件或汇总验证字段发生变化。 |
business.status.updated | 企业实体的状态发生变化,例如人工审核、KYB 结果或黑名单操作之后。 |
business.data.updated | 企业实体的资料、计数器、元数据、注册字段或汇总验证字段发生变化。 |
activity.created | 可添加到 subscribed_events 中,并受 Try Webhook 支持,但 Didit 目前不会为实时流量投递该事件。 |
transaction.created | 交易监控交易已创建,且其初始规则评估已完成。 |
transaction.status.updated | 交易在规则、分析师审核、整改、服务商更新或 API/控制台操作之后状态发生变化;加密货币筛查在后台重试并完成后,也会发送一次。 |
travel_rule.status.updated | Travel Rule 交换的状态发生变化。 |
workflow.compliance_changed | 已发布工作流在重新评估后,其合规状态发生变化。 |
transaction_rule_suggestions.created | 规则建议运行提出新的规则变更。 |
investigator.*)和 Authentication(auth.*)事件系列同样可以接受。每个事件及其 payload 都列在 Webhook 中。
常见的订阅组合:
{
"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"
]
}
授权
您的应用 API 密钥,可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域:针对每个资源设为无权限、只读或读写,限定于特定工作流或已通过的会话、限定于 IP 地址列表,以及设置到期日期。401 表示密钥错误、已撤销或已过期;403 表示未发送密钥、密钥无权访问该资源或操作,或请求来自其 IP 列表之外的地址;在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null;没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。
请求体
在 Console → Webhooks 中显示的便于人类阅读的名称。当您有多个目标时有助于进行区分(例如 "Prod"、"Staging mirror")。
255接收 POST 请求的 HTTPS URL。在应用的目标中必须唯一。请使用稳定且经过强化的 endpoint:Didit 会按退避计划重试失败的投递。
2000为 false 时,目标会被保存,但 Didit 不会向其推送任何 Webhook。适用于您希望保留但暂不启用的配置。
Didit 将发送的 payload 架构版本。v3 为当前/推荐格式;保留较旧版本是为了向后兼容历史集成。
v1, v2, v3 要投递的事件。实际上为必填项:显式传入 [] 将被拒绝并返回 400,而省略该字段会创建一个没有任何订阅的目标,该目标不会接收任何内容。
1支持的 Webhook 事件名称。请在 subscribed_events 中使用这些完全匹配的字符串;不支持的值将被拒绝。
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 ["status.updated", "data.updated"]
响应
目标已创建。secret_shared_key 是 HMAC 签名密钥,请立即保存。
目标稳定标识符。在后续调用中用作 {destination_uuid}。
v1, v2, v3 与该目标绑定的自动生成的 HMAC 签名密钥(43 个字符的 URL 安全 token)。用于验证传入 Webhook 的签名请求头。对于使用 API 密钥的调用方始终完整返回;控制台用户需要具备 read:webhooks 权限,否则将看到空字符串。
目标当前签名密钥的最后四位字符,以便您区分不同的密钥。不足以用于验证签名。
此 Webhook 目标的事件过滤器。Didit 仅投递事件类型与这些值之一完全匹配的 Webhook,不支持通配符订阅。发送时,列表必须包含至少一个有效事件(显式传入 [] 将被拒绝并返回 400);列表为空的目标(创建时省略该字段)不会接收任何内容。更新时,列表会被整体替换,绝不会进行合并。
1支持的 Webhook 事件名称。请在 subscribed_events 中使用这些完全匹配的字符串;不支持的值将被拒绝。
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 ["status.updated", "data.updated"]
创建该目标的 Business Console 成员的邮箱。通过 API 密钥创建的目标为 null。
创建该目标的 Business Console 成员姓名。使用 API 密钥创建的目标为 null。
投递健康状态。failing:自该目标上次成功响应以来,已有 3 个或更多连续事件在首次投递尝试时失败(参见 failing_streak)。degraded:非 failing 状态,但在过去 24 小时内有一次投递尝试失败,且后续没有尝试成功投递该事件;成功投递该事件的重试或重新发送会清除此状态。healthy:均非上述情况。独立于 enabled。失败的尝试是指响应 HTTP 400 或以上,或者完全没有响应的尝试。
healthy, degraded, failing 在最近 30 天内,自该目标上次成功响应以来,首次投递尝试失败的连续事件数量。重试不计入,任何成功的尝试(包括重试或重新发送)都会结束该连续记录。自上次成功以来没有事件失败时为 0。
当前 failing_streak 中第一次失败尝试的时间。当 failing_streak 为 0 时为 null。
在过去 30 天内,目标上次以低于 400 的 HTTP 状态响应投递的时间。如果在此时间窗口内没有以低于 400 的 HTTP 状态响应,则为 null。
拥有该目标的应用的环境。
live, sandbox 最近 metrics_window_days(30)天的投递指标。last_delivery_at 为最近一次尝试的时间,无论其何时发生。
Show child attributes
Show child attributes