Webhook 报文与回执参考
本页内容
接收端完成订阅配置后,可用本页核对请求头、事件正文、签名与回执。普通业务事件和端点验证使用不同回执,须分别处理。
使用前准备
Webhook 是平台向您的服务发送的 HTTP 请求。它使用独立的回调密钥,不使用 AccessKey 请求签名。先按接入指南创建订阅并验证地址,再用本页核对报文。
当前事件定义版本为 1.3.0-preview.1,正文中的 schema_version 为字符串 "1"。可下载Webhook JSON 定义用于校验;事件含义和业务处理见事件类型与通知来源。
接收请求
平台以 POST 请求您在订阅中填写的公网 HTTPS 地址。地址使用有效证书和 443 端口,不包含账号、查询参数或片段;平台不跟随重定向。正文为 UTF-8 JSON,最多 8192 字节。
| 请求头 | 必填 | 说明 |
|---|---|---|
X-Cloudsign-Webhook-Id | 是 | 订阅 ID。与您预先保存的受信订阅核对。 |
X-Cloudsign-Event-Id | 是 | 事件 ID。与正文的 id 相同。 |
X-Cloudsign-Timestamp | 是 | 本次投递的 Unix 秒,以十进制文本传递。与接收端时钟的偏差不得超过 300 秒。 |
X-Cloudsign-Signature | 是 | 以 v1= 开头的 HMAC-SHA256 签名。 |
这四个请求头各出现一次,头名称不区分大小写。HTTP 接入层应拒绝重复头,保留原始正文后再验签。不能先解析 JSON、格式化、解压或转码,再用修改后的字节验证签名。
请求头的精确格式
- 订阅 ID:
WHK后接 40 位小写十六进制字符。 - 事件 ID:
E后接 32 位小写十六进制字符。 - 投递时间戳:9–12 位十进制数字,首位不能为零。
- 签名:
v1=后接 64 位小写十六进制字符。
读取事件正文
所有事件都有下列六个字段。data 随事件类型变化,详见事件数据。当前定义不接受额外字段。
| 字段 | 类型 | 说明 |
|---|---|---|
schema_version | string | 正文版本,当前固定为 "1"。 |
id | string | 事件 ID;用于去重,同一事件重投时保持不变。 |
webhook_id | string | 订阅 ID;须与请求头及您的受信配置一致。 |
type | string | 事件名称,例如 signing.succeeded。 |
created_at | integer | 事件创建的 Unix 秒。它不是本次投递时间,重投时不更新。 |
data | object | 对应事件的业务数据;地址验证事件只包含挑战值。 |
{
"schema_version": "1",
"id": "E11111111111111111111111111111111",
"webhook_id": "WHK2222222222222222222222222222222222222222",
"type": "signing.succeeded",
"created_at": 1794787200,
"data": {
"app_id": "A33333333333333333333333333333333",
"resource_id": "J44444444444444444444444444444444",
"status": "succeeded"
}
}以上 ID 和时间仅用于说明格式。接收端从受信订阅配置读取来源和应用范围;正文没有 source_scope 字段。端点验证事件也没有业务应用 ID。
验证签名与归属
- 从自己的配置读取回调密钥和预期订阅 ID。不要根据传入 URL、路径或正文任意读取外部密钥。
- 校验投递时间与原始正文签名,再校验事件结构以及请求头和正文的 ID 是否一致。
- 业务事件还需核对
data.app_id、订阅来源和允许的事件类型。端点验证按挑战流程处理。 - 在持久事务中去重并保存事件或业务结果。提交成功后再返回回执。
推荐使用 SDK 的 Webhook 验签与回执助手。Python 接收示例见运行事件接收服务;C 接入见C SDK 通知验证。
自行实现 CSWH1
按顺序将 CSWH1、订阅 ID、事件 ID、投递时间戳、原始正文的 SHA-256 小写十六进制摘要,用换行符 LF 连接,末尾不追加换行。用回调密钥的 UTF-8 字节计算 HMAC-SHA256,得到小写十六进制摘要并添加 v1=。使用恒时比较。
密钥格式为 CSW_ 后接 43 位 URL 安全字符。不得用 AccessKey Secret 代替。验签前的正文不得重新序列化;验签后再按 JSON 结构处理,并拒绝重复字段。
返回接收回执
平台只在收到 HTTP 2xx、Content-Type: application/json 且回执内容符合要求时,确认本次投递成功。下面使用 HTTP 202;只有状态码、空正文或 HTML 页面都不够。回执最多 4096 字节。
{
"event_id": "E11111111111111111111111111111111"
}event_id 必须等于已验证并提交的事件 ID。去重记录已存在且内容一致时,可以再次返回相同回执。接收端暂时无法保存事件时应返回非 2xx,由平台按规则重投。
端点验证回执
收到 endpoint.challenge 后,先验签,再回显 event_id 和 data.challenge,并返回 SDK 计算的 proof。不执行签名、发布或资金业务。
{
"event_id": "E11111111111111111111111111111111",
"challenge": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"proof": "v1=bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}上例 proof 仅说明格式,不能直接使用。它是对 LF 连接的 CSWH1-ACK、订阅 ID、事件 ID、挑战值计算 HMAC-SHA256,再添加 v1=。推荐调用 SDK 生成。
排查投递失败
先在开发者中心查看订阅状态和投递记录,再按失败环节处理。平台连接接收地址的超时为 2 秒,整个请求最多 5 秒;接收端宜快速提交事件,耗时业务交给自己的后台任务。
- 连接失败:核对公网 DNS、HTTPS 证书、443 端口和反向代理,不使用跳转地址。
- 签名失败:核对独立回调密钥、原始正文、四个请求头与系统时钟。
- 回执失败:核对 JSON 类型、事件 ID,以及挑战事件的 challenge 和 proof。
- 业务状态与通知不同:查询原资源的当前状态;通知可能重复或乱序。
重试次数、人工重放期限和业务留存分别计算,见留存与重放。