跳转到主要内容
POST
curl
Webhook 目标可让您将不同的 Didit 事件发送到不同的 URL。每个目标都有各自的 secret_shared_key、webhook_version 和 subscribed_events 列表。

subscribed_events 的工作方式

subscribed_events 是必填的精确事件名称数组。仅当 payload 中的 webhook_type 与数组中的某个值匹配时,Didit 才会将 Webhook 投递到此目标。
  • 至少包含一个事件。
  • 仅使用下方列出的受支持事件名称。
  • 请添加您希望投递的每个事件;没有 * 或 all 这样的通配符值。
  • 若要将不同的产品领域路由到不同的系统,请使用不同的 subscribed_events 列表创建多个目标。

事件目录

Investigator(investigator.*)和 Authentication(auth.*)事件系列同样可以接受。每个事件及其 payload 都列在 Webhook 中。 常见的订阅组合:
有关 payload 示例和签名代码,请参阅 Webhook 指南。

授权

x-api-key
string
header
必填

您的应用 API 密钥,可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域:针对每个资源设为无权限、只读或读写,限定于特定工作流或已通过的会话、限定于 IP 地址列表,以及设置到期日期。401 表示密钥错误、已撤销或已过期;403 表示未发送密钥、密钥无权访问该资源或操作,或请求来自其 IP 列表之外的地址;在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null;没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。

请求体

application/json
label
string
必填

在 Console → Webhooks 中显示的便于人类阅读的名称。当您有多个目标时有助于进行区分(例如 "Prod"、"Staging mirror")。

Maximum string length: 255
url
string<uri>
必填

接收 POST 请求的 HTTPS URL。在应用的目标中必须唯一。请使用稳定且经过强化的 endpoint:Didit 会按退避计划重试失败的投递。

Maximum string length: 2000
enabled
boolean
默认值:true

为 false 时,目标会被保存,但 Didit 不会向其推送任何 Webhook。适用于您希望保留但暂不启用的配置。

webhook_version
enum<string>

Didit 将发送的 payload 架构版本。v3 为当前/推荐格式;保留较旧版本是为了向后兼容历史集成。

可用选项:
v1,
v2,
v3
subscribed_events
enum<string>[]

要投递的事件。实际上为必填项:显式传入 [] 将被拒绝并返回 400,而省略该字段会创建一个没有任何订阅的目标,该目标不会接收任何内容。

Minimum array length: 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
示例:

响应

目标已创建。secret_shared_key 是 HMAC 签名密钥,请立即保存。

uuid
string<uuid>

目标稳定标识符。在后续调用中用作 {destination_uuid}。

label
string
url
string<uri>
enabled
boolean
webhook_version
enum<string>
可用选项:
v1,
v2,
v3
secret_shared_key
string

与该目标绑定的自动生成的 HMAC 签名密钥(43 个字符的 URL 安全 token)。用于验证传入 Webhook 的签名请求头。对于使用 API 密钥的调用方始终完整返回;控制台用户需要具备 read:webhooks 权限,否则将看到空字符串。

secret_last4
string

目标当前签名密钥的最后四位字符,以便您区分不同的密钥。不足以用于验证签名。

previous_secret_expires_at
string<date-time> | null

在 Business Console 中轮换目标的签名密钥后设置 24 小时。在此期间,向该目标进行的每次投递还会携带使用被替换密钥生成的 X-Signature-Previous、X-Signature-V2-Previous 和 X-Signature-Simple-Previous(请参阅签名验证)。如果在过去 24 小时内未发生轮换,则为 null。

subscribed_events
enum<string>[]

此 Webhook 目标的事件过滤器。Didit 仅投递事件类型与这些值之一完全匹配的 Webhook,不支持通配符订阅。发送时,列表必须包含至少一个有效事件(显式传入 [] 将被拒绝并返回 400);列表为空的目标(创建时省略该字段)不会接收任何内容。更新时,列表会被整体替换,绝不会进行合并。

Minimum array length: 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
示例:
created_by_email
string | null

创建该目标的 Business Console 成员的邮箱。通过 API 密钥创建的目标为 null。

created_by_name
string | null

创建该目标的 Business Console 成员姓名。使用 API 密钥创建的目标为 null。

created_at
string<date-time>
updated_at
string<date-time>
health_status
enum<string>

投递健康状态。failing:自该目标上次成功响应以来,已有 3 个或更多连续事件在首次投递尝试时失败(参见 failing_streak)。degraded:非 failing 状态,但在过去 24 小时内有一次投递尝试失败,且后续没有尝试成功投递该事件;成功投递该事件的重试或重新发送会清除此状态。healthy:均非上述情况。独立于 enabled。失败的尝试是指响应 HTTP 400 或以上,或者完全没有响应的尝试。

可用选项:
healthy,
degraded,
failing
failing_streak
integer

在最近 30 天内,自该目标上次成功响应以来,首次投递尝试失败的连续事件数量。重试不计入,任何成功的尝试(包括重试或重新发送)都会结束该连续记录。自上次成功以来没有事件失败时为 0。

failing_since
string<date-time> | null

当前 failing_streak 中第一次失败尝试的时间。当 failing_streak 为 0 时为 null。

last_success_at
string<date-time> | null

在过去 30 天内,目标上次以低于 400 的 HTTP 状态响应投递的时间。如果在此时间窗口内没有以低于 400 的 HTTP 状态响应,则为 null。

environment
enum<string>

拥有该目标的应用的环境。

可用选项:
live,
sandbox
summary
object

最近 metrics_window_days(30)天的投递指标。last_delivery_at 为最近一次尝试的时间,无论其何时发生。

最后修改于 2026年11月7日