Webhook 事件、签名与可靠投递草案
定义事件信封、验签、防重放、去重、重试和失败补偿。
事件的作用与拟议范围
Webhook 用于通知外部系统发生了状态变化,接收方再通过授权查询获取必要资料。拟议事件包括 task-request.status-changed、delivery.submitted 和 connection.revoked。它们是设计名称,不表示已有订阅入口或事件投递服务。订阅管理与密钥发行需先实现并验收。
事件信封示例
事件携带最小必要信息,避免直接发送任务全文和敏感结果。事件 ID 用于业务去重,deliveryId 标识一次投递;对同一事件重试时保留事件 ID。时间统一使用带时区的 ISO 8601。
{
"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 验签。该约定需发送端与接收端共同实现。
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 端点,验证域名和重定向,避免服务端请求伪造。未实现和验证这些机制前,不应依赖此草案启动生产业务。