跳转到主要内容
1签 (OneSign)

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_versionstring正文版本,当前固定为 "1"。
idstring事件 ID;用于去重,同一事件重投时保持不变。
webhook_idstring订阅 ID;须与请求头及您的受信配置一致。
typestring事件名称,例如 signing.succeeded。
created_atinteger事件创建的 Unix 秒。它不是本次投递时间,重投时不更新。
dataobject对应事件的业务数据;地址验证事件只包含挑战值。
签名成功事件正文
{
    "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。

验证签名与归属

  1. 从自己的配置读取回调密钥和预期订阅 ID。不要根据传入 URL、路径或正文任意读取外部密钥。
  2. 校验投递时间与原始正文签名,再校验事件结构以及请求头和正文的 ID 是否一致。
  3. 业务事件还需核对 data.app_id、订阅来源和允许的事件类型。端点验证按挑战流程处理。
  4. 在持久事务中去重并保存事件或业务结果。提交成功后再返回回执。

推荐使用 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。
  • 业务状态与通知不同:查询原资源的当前状态;通知可能重复或乱序。

重试次数、人工重放期限和业务留存分别计算,见留存与重放。