> ## 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 > 在 Didit 中注册新的 Webhook 目标，配置版本、订阅事件和目标专属签名密钥。可编程管理 Webhook，按次计费。 创建 Webhook 目标 API 提示词 将提示词复制到剪贴板 \

\`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` 是必填的精确事件名称数组。仅当 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](https://docs.didit.me/zh/transaction-monitoring/travel-rule.md) 交换的状态发生变化。 | | `workflow.compliance_changed` | 已发布工作流在重新评估后，其合规状态发生变化。 | | `transaction_rule_suggestions.created` | 规则建议运行提出新的规则变更。 |Investigator（`investigator.*`）和 Authentication（`auth.*`）事件系列同样可以接受。每个事件及其 payload 都列在 [Webhook](https://docs.didit.me/zh/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/zh/integration/webhooks.md)。 ## OpenAPI ````yaml zh/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 目标。响应中包含自动生成的 `secret_shared_key` HMAC 签名密钥（稍后也可通过 `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: >- 接收 `POST` 请求的 HTTPS URL。在应用的目标中必须唯一。请使用稳定且经过强化的 endpoint：Didit 会按退避计划重试失败的投递。 maxLength: 2000 enabled: type: boolean default: true description: >- 为 `false` 时，目标会被保存，但 Didit 不会向其推送任何 Webhook。适用于您希望保留但暂不启用的配置。 webhook_version: type: string enum: - v1 - v2 - v3 description: Didit 将发送的 payload 架构版本。`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 签名密钥（43 个字符的 URL 安全 token）。用于验证传入 Webhook 的签名请求头。对于使用 API 密钥的调用方始终完整返回；控制台用户需要具备 `read:webhooks` 权限，否则将看到空字符串。 secret_last4: type: string description: 目标当前签名密钥的最后四位字符，以便您区分不同的密钥。不足以用于验证签名。 previous_secret_expires_at: type: string format: date-time nullable: true description: >- 在 Business Console 中轮换目标的签名密钥后设置 24 小时。在此期间，向该目标进行的每次投递还会携带使用被替换密钥生成的 `X-Signature-Previous`、`X-Signature-V2-Previous` 和 `X-Signature-Simple-Previous`（请参阅[签名验证](/zh/integration/webhooks#签名验证)）。如果在过去 24 小时内未发生轮换，则为 `null`。 subscribed_events: $ref: '#/components/schemas/WebhookSubscribedEvents' created_by_email: type: string nullable: true description: 创建该目标的 Business Console 成员的邮箱。通过 API 密钥创建的目标为 `null`。 created_by_name: type: string nullable: true description: 创建该目标的 Business Console 成员姓名。使用 API 密钥创建的目标为 `null`。 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` 中第一次失败尝试的时间。当 `failing_streak` 为 `0` 时为 `null`。 last_success_at: type: string format: date-time nullable: true description: >- 在过去 30 天内，目标上次以低于 400 的 HTTP 状态响应投递的时间。如果在此时间窗口内没有以低于 400 的 HTTP 状态响应，则为 `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 密钥，可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域：针对每个资源设为无权限、只读或读写，限定于特定工作流或已通过的会话、限定于 IP 地址列表，以及设置到期日期。401 表示密钥错误、已撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或操作，或请求来自其 IP 列表之外的地址；在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null；没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.