文档开发者接入

Webhook 事件、签名与可靠投递草案

定义事件信封、验签、防重放、去重、重试和失败补偿。

事件的作用与拟议范围

Webhook 用于通知外部系统发生了状态变化,接收方再通过授权查询获取必要资料。拟议事件包括 task-request.status-changed、delivery.submitted 和 connection.revoked。它们是设计名称,不表示已有订阅入口或事件投递服务。订阅管理与密钥发行需先实现并验收。

事件信封示例

事件携带最小必要信息,避免直接发送任务全文和敏感结果。事件 ID 用于业务去重,deliveryId 标识一次投递;对同一事件重试时保留事件 ID。时间统一使用带时区的 ISO 8601。

json
{
  "specVersion": "0.1",
  "id": "evt_example",
  "deliveryId": "dlv_example_1",
  "type": "task-request.status-changed",
  "occurredAt": "2026-11-16T08:00:00Z",
  "companyId": "co_example",
  "data": {
    "resourceId": "tr_example",
    "revision": 3,
    "status": "awaiting_review"
  }
}

建议签名契约

每个订阅配置独立密钥,签名采用 HMAC-SHA256。拟议请求头为 DigitalHe-Delivery-Id、DigitalHe-Timestamp、DigitalHe-Signature;签名值为 v1= 后接小写十六进制摘要。签名串为“timestamp + 点号 + deliveryId + 点号 + 原始请求体字节”,不得用重新序列化后的 JSON 验签。该约定需发送端与接收端共同实现。

text
message = UTF8(timestamp + '.' + deliveryId + '.') || rawBodyBytes
signature = 'v1=' + hexLower(HMAC_SHA256(subscriptionSecret, message))

Verify timestamp format and allowed skew
Recompute signature over the raw bytes
Compare equal-length digests in constant time
Parse JSON; require body.deliveryId == header delivery ID
Authorize subscription and company; persist event ID uniquely
Acknowledge after durable enqueue; process asynchronously

防重放、轮换与去重

可先讨论 5 分钟时间偏差窗口,正式值需按网络和时钟条件约定。每次重试重新生成时间戳与投递标识,并保留事件 ID;接收端对事件 ID 持久化去重。密钥轮换期间限定新旧密钥的重叠时间,密钥与签名不写入公开日志。只记录脱敏的订阅、事件、投递和验签结果。

响应、重试与顺序

建议接收方持久化入队后快速返回 2xx,业务处理异步进行;只有验签通过但落库失败时返回可重试错误。发送端对超时、429 和 5xx 有限重试,其他 4xx 暂停并告警。具体响应超时、重试间隔、最长保留时间和次数上线前公布。投递采用至少一次语义,不承诺顺序或恰好一次;消费者通过资源版本识别旧事件。

失败补偿与接入验收

发送端需要失败投递记录、暂停与恢复、授权后重放和状态查询能力;接收端要支持重复与乱序事件、队列失败、密钥过期和服务重启。订阅地址只允许经批准的 HTTPS 端点,验证域名和重定向,避免服务端请求伪造。未实现和验证这些机制前,不应依赖此草案启动生产业务。

返回全部文档下一篇指南

还有疑问?

查看专家支持