跳转到主要内容
PATCH
curl
rotate_secret_key 仅轮换应用级密钥,该密钥用于对发送到旧版 webhook_url 的投递进行签名。每个 Webhook 目标 都使用其自己的 secret_shared_key 签名,此调用不会更改该密钥。
保留字段与您在 Business Console → App Settings → Data retention 中设置的策略相同。更改这些字段前,请先阅读数据保留,尤其是生物特征模板保留。allowed_return_hosts 在注册返回目标中有所说明。 biometric_consent_mode(auto、always 或 never)用于设置验证流程在人脸采集前何时请求明确的生物特征同意。请参阅生物特征同意。 如需先读取当前值,请调用获取 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

仅发送要更改的字段。目标不在此处管理。

webhook_url
string<uri> | null

旧版应用级 Webhook URL。Didit 仅在应用未启用任何目标时使用它,且仅用于 status.updated 和 data.updated。它不会创建目标,并且下次对目标的创建、更新或删除操作都会替换它。若要接收 Webhook,请改用 POST /v3/webhook/destinations/ 创建目标。

Maximum string length: 2000
webhook_version
enum<string>

传统 webhook_url 的 payload 版本。

可用选项:
v1,
v2,
v3
rotate_secret_key
boolean
默认值:false

true 会立即将应用层级的 secret_shared_key 替换为新的随机值;新值包含在响应中。目标密钥不会更改。每次传入 true 的调用都会生成一个新密钥,因此该操作不具备幂等性。

capture_method
enum<string>

旧版应用设置。验证流程不会读取它。

可用选项:
MOBILE,
MOBILE_AND_DESKTOP
data_retention_months
integer | null

自动删除期限(以月为单位,一个月计为 30 天),或填 null 表示不自动删除。更改同样适用于现有会话:早于新设定月限的所有用户验证会话都将被自动删除,且该删除操作不可逆。

必填范围: 1 <= x <= 120
face_retention_policy
enum<string>

当会话被删除时,对该会话的人脸特征向量的处理方式。retain_until_user_deleted 要求在同一次请求中提供 face_retention_days 或已预先设置该参数。变更仅适用于此后的会话删除;不会创建或清除任何现有的生物特征模板。

可用选项:
delete_with_session,
retain_until_user_deleted
face_retention_days
integer | null

在 retain_until_user_deleted 策略下生物特征模板的保留期(以天为单位)。

必填范围: 1 <= x <= 3650

托管流程和原生 SDK 何时在人脸采集前向当事人请求明确的生物识别同意。auto(默认)仅在适用触发条件时请求:当事人声明的州、当事人的 IP 或身份证件签发地位于伊利诺伊州、德克萨斯州或科罗拉多州,或者当事人看似位于美国境内且所在州未知。always 会向工作流中需要采集人脸的每个人请求。never 则从不显示该步骤,由您在拍摄自拍照前自行收集同意。每次更改都会记录在审计日志中。请参阅生物识别同意。

可用选项:
auto,
always,
never
allowed_return_hosts
string[]

替换数字身份钱包返回主机的整个列表。仅支持纯主机名,例如 shop.example.com:不支持协议、端口、路径或通配符。值将转换为小写并删除重复项。发送 [] 以清空列表。

Maximum array length: 20
Maximum string length: 253
allowed_domains
string[]

替换允许的源(origins)的整个列表。托管验证流程可以嵌入其中并通过会话回调将用户发送回这些源(例如 https://app.example.com;http 仅适用于 localhost)。服务器到服务器的调用不受影响。空列表表示没有限制。Didit 以小写形式存储每个源,不包含默认端口。无效条目会针对 allowed_domains 返回 400。发送 [] 以移除限制。

Maximum array length: 50
Maximum string length: 300
示例:

响应

更新后的完整配置,结构与 GET /v3/webhook/ 相同。轮换密钥时,请在丢弃响应前存储新的 secret_shared_key。

应用级 Webhook 配置、保留策略和数字身份(Digital ID)钱包返回主机,以及所有 Webhook 目标。

webhook_url
string<uri> | null
必填

应用级(旧版)Webhook URL。Didit 仅在应用没有已启用的目标时才向其发送事件,且仅发送 status.updated 和 data.updated。每次创建、更新或删除目标时,都会将其设置为最早启用的目标的 URL;若无已启用的目标,则设置为 null。

webhook_version
enum<string>
必填

传统 webhook_url 的 payload 版本。每个目标都有其独立的 webhook_version。

可用选项:
v1,
v2,
v3
secret_shared_key
string
必填

应用级签名密钥(43 字符的 URL 安全 token)。它仅对投递到旧版 webhook_url 的事件进行签名;每个目标则使用各自的 secret_shared_key 进行签名。通过 API 密钥调用的调用方始终会完整接收该密钥;没有 read:webhooks 权限的控制台用户将收到空字符串。

capture_method
enum<string>
必填

旧版应用设置。验证流程不会读取它:采集选项按工作流进行配置。

可用选项:
MOBILE,
MOBILE_AND_DESKTOP
data_retention_months
integer | null
必填

自动删除窗口。在此月数以前(一个月按 30 天计算)创建的用户验证会话将被自动删除,且该删除不可逆。null 表示会话绝不会被自动删除。参见数据保留。

必填范围: 1 <= x <= 120
face_retention_policy
enum<string>
必填

当会话被删除时,对该会话的人脸特征向量的处理方式。delete_with_session(默认)会随会话一同将其删除。retain_until_user_deleted 为自选的生物特征模板保留:与用户关联的不含图像的生物特征模板会被单独管理,直至其数据保留期结束、用户被删除或您主动清除它。

可用选项:
delete_with_session,
retain_until_user_deleted
face_retention_days
integer | null
必填

在 retain_until_user_deleted 策略下生物特征模板的保留期(以天为单位)。设置该策略时必填。

必填范围: 1 <= x <= 3650
available_events
object[]
必填

目标可以订阅的每种事件类型,附带显示标签。

allowed_return_hosts
string[]
必填

独立数字身份钱包验证可通过其 return_url 将用户送回的主机名(精确匹配,仅限 HTTPS)。您的白标域名也始终被允许。请参阅注册您的返回目标。

Maximum array length: 20
Maximum string length: 253
endpoints
object[]
必填

该应用的每个 Webhook 目标,按时间正序排列,每个目标均附带其签名密钥。此处为只读:使用 /v3/webhook/destinations/ 系列 endpoint 管理目标。

托管流程和原生 SDK 何时在人脸采集前向当事人请求明确的生物识别同意。auto(默认)仅在适用触发条件时请求:当事人声明的州、当事人的 IP 或身份证件签发地位于伊利诺伊州、德克萨斯州或科罗拉多州,或者当事人看似位于美国境内且所在州未知。always 会向工作流中需要采集人脸的每个人请求。never 则从不显示该步骤,由您在拍摄自拍照前自行收集同意。每次更改都会记录在审计日志中。请参阅生物识别同意。

可用选项:
auto,
always,
never
allowed_domains
string[]

托管验证流程可以嵌入并可通过会话回调将用户重定向回的源(Origin,例如 https://app.example.com;http 仅适用于 localhost)。服务器到服务器的调用不受影响。空列表表示无限制。Didit 会将每个源以小写形式存储,且不包含默认端口。无效条目将导致 allowed_domains 验证失败并返回 400。

Maximum array length: 50
Maximum string length: 300
示例:
最后修改于 2026年11月7日