> ## 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 目标的标签、URL、启用状态、版本及订阅事件。支持程序化管理 Webhook，按次计费，无需签约。 更新 Webhook 目标 API 提示词 将提示词复制到剪贴板 \

\`Update a Didit webhook destination through the Management API.

Endpoint:
PATCH https://verification.didit.me/v3/webhook/destinations/{destination_uuid}/

Authentication:
Use the x-api-key header with my Didit API key.

Goal:
\- Change a destination's label, url, enabled state, webhook_version, or subscribed_events. Send only the fields you want to change.

Path parameter:
\- destination_uuid — the destination UUID from GET /v3/webhook/destinations/.

Request body (application/json) — all fields optional:
\{
"label": "Updated label",
"url": "https://yourapp.com/webhooks/v2",
"enabled": false,
"webhook_version": "v3",
"subscribed_events": ["status.updated", "data.updated", "transaction.created"]
}

Critical semantics:
\- subscribed_events is replaced wholesale, NOT merged. To add an event, GET the current destination, append to the list, and send the full array back. Sending [] returns 400.
\- url must remain unique among the application's destinations.
\- A uuid in the body is ignored: the path names the destination.
\- webhook_version applies to future deliveries only. Already-queued deliveries use the version that was active when they were enqueued.
\- The signing secret (secret_shared_key) is NOT rotated by PATCH. Console offers a manual rotation flow. For 24 hours after a rotation, every delivery also carries X-Signature-Previous, X-Signature-V2-Previous and X-Signature-Simple-Previous, made with the replaced secret, and previous_secret_expires_at says when that ends.
\- Changing url does not move automatic retries of deliveries already made: they go to the URL the first attempt used. A manual resend goes to the destination's current URL.

Example call (replace subscription list):
curl -X PATCH "https://verification.didit.me/v3/webhook/destinations/{destination_uuid}/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"subscribed_events": ["status.updated", "data.updated", "transaction.created"]}'

\# Pause a destination without losing config:
curl -X PATCH "https://verification.didit.me/v3/webhook/destinations/{destination_uuid}/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"enabled": false}'

Failure modes:
\- 400 — empty subscribed_events, unknown event name, duplicate url among destinations, or invalid webhook_version.
\- 401 — missing or malformed x-api-key.
\- 403 — canonical { "detail": "You do not have permission to perform this action." } envelope.
\- 404 — destination not found in this application.

Side effects:
\- Subsequent webhook deliveries respect the new url, enabled flag, and subscribed_events list.

For the full integration shape, see /integration/integration-prompt.`

\
粘贴到 使用此 endpoint更改目标发送 Webhook 的地址以及目标接收的事件。## 更新 `subscribed_events`发送 `subscribed_events` 时，请提供更新后应保持订阅的完整事件列表。该数组会替换之前的订阅集合。```json theme={null} { "subscribed_events": [ "status.updated", "data.updated", "transaction.created", "transaction.status.updated" ] } ```支持的值如下：| 事件 | 含义 | | - | - | | `status.updated` | 用户验证（KYC）或企业验证（KYB）会话的状态已变更。 | | `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` | Travel Rule 交换的状态已变更。 | | `workflow.compliance_changed` | 已发布工作流的合规状态已变更。 | | `transaction_rule_suggestions.created` | 一次规则建议运行提出了新的规则变更。 |调查员（`investigator.*`）和认证（`auth.*`）事件系列也受支持；完整列表请参阅 [Webhook](https://docs.didit.me/zh/integration/webhooks.md#事件类型)。有关详细的事件说明和常见订阅集合，请参阅[创建目标指南](https://docs.didit.me/zh/management-api/webhook/create-destination.md)。 ## OpenAPI ````yaml zh/openapi-25.json PATCH /v3/webhook/destinations/{destination_uuid}/ 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/{destination_uuid}/: patch: tags: - Webhook summary: 更新 Webhook 目标 description: >- 更新 Webhook 目标。**`subscribed_events` 将被整项替换，而非合并**：请先获取、追加然后再重新发送。密钥不会轮换。请求体中的 `uuid` 将被忽略：以路径指定的 Webhook 目标为准。 operationId: update_webhook_destination parameters: - name: destination_uuid in: path required: true description: 要更新的 Webhook 目标的 UUID。 schema: type: string format: uuid example: 11111111-2222-3333-4444-555555555555 requestBody: required: true content: application/json: schema: type: object properties: label: type: string description: 新的人类可读名称。 url: type: string format: uri description: 新目标 URL。在应用内必须唯一。 enabled: type: boolean description: 设为 `false` 可暂停向此目标的投递而无需将其删除。 webhook_version: type: string enum: - v1 - v2 - v3 description: 用于未来投递的新 payload 模式版本。 subscribed_events: $ref: '#/components/schemas/WebhookSubscribedEvents' examples: Pause destination: value: enabled: false Add transaction events: value: subscribed_events: - status.updated - data.updated - transaction.created - transaction.status.updated Move target URL: value: label: Production session webhooks v2 url: https://api.yourapp.com/webhooks/didit/v2 responses: '200': description: >- 已更新 Webhook 目标。响应体结构与 `GET /v3/webhook/destinations/{destination_uuid}/` 相同。 content: application/json: schema: type: object properties: uuid: type: string format: 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 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: Paused: value: uuid: 11111111-2222-3333-4444-555555555555 label: Production session webhooks url: https://yourapp.com/webhooks/didit enabled: false 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-01-04T08:00:00Z' updated_at: '2026-05-17T11:02:55Z' health_status: healthy failing_streak: 0 failing_since: null last_success_at: '2026-05-17T09:21:18Z' environment: live summary: total_deliveries: 12453 failed_deliveries: 14 error_rate_percentage: 0 min_response_time_ms: 41 avg_response_time_ms: 187 max_response_time_ms: 2103 last_delivery_at: '2026-05-17T09:21:18Z' metrics_window_days: 30 '400': description: 验证失败（重复的 URL、事件列表为空/未知、请求体格式错误）。 content: application/json: examples: Duplicate URL: value: url: - >- This webhook destination already exists for the application. Empty events: value: subscribed_events: - At least one subscribed event is required. '403': description: API 密钥缺失、格式错误、已过期或作用域属于其他应用。密钥缺失返回 `403`；密钥错误、已撤销或已过期返回 `401`。 content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. '404': description: 具有此 UUID 的目标不存在（或已被删除，或属于其他应用）。 content: application/json: examples: Not found: value: detail: Webhook destination not found. '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 PATCH 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "subscribed_events": [ "status.updated", "data.updated", "transaction.created" ] }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.webhooks.destinations.update( "11111111-2222-3333-4444-555555555555", enabled=False, ) 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.update("11111111-2222-3333-4444-555555555555", { enabled: false, }); 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.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.WebhooksDestinationsUpdateParams{\n\tEnabled: didit.Bool(false),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import me.didit.Didit; import me.didit.types.WebhooksDestinationsUpdateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.webhooks().destinations().update("11111111-2222-3333-4444-555555555555", WebhooksDestinationsUpdateParams.builder() .enabled(false) .build()); System.out.println(result); - lang: php label: PHP source: >- webhooks->destinations->update('11111111-2222-3333-4444-555555555555', [ 'enabled' => false, ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.webhooks.destinations.update( "11111111-2222-3333-4444-555555555555", enabled: false ) 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.UpdateAsync("11111111-2222-3333-4444-555555555555", new WebhooksDestinationsUpdateParams { Enabled = false, }); 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.