接收 Webhook 事件通知
本页内容
平台可在上传、签名、发布或订单状态变化后,向您配置的 HTTPS 地址发送通知。接收端需要验签、去重并在业务保存成功后返回回执。
了解通知流程
- 配置订阅
- 验证接收地址
- 接收并验证事件
- 持久保存并确认
Webhook 用于减少轮询,最终业务状态仍以资源查询为准。通知可能重复或乱序;接收端需要按事件 ID 去重,不能只按 HTTP 请求到达次数处理业务。
首次接入可先运行Python 接收示例;已有 HTTP 服务时,按报文与回执参考接入验签和持久事务。
创建订阅并验证地址
- 在开发者中心选中自己的 API 应用,确认通知功能和所需事件权限已开放。
- 填写 HTTPS 接收地址,绑定业务应用并选择事件及来源。
- 保存独立的回调密钥,配置接收端的受信订阅 ID 与应用 ID。
- 处理
endpoint.challenge:验签后返回包含 challenge 和 proof 的回执。地址验证成功后才开始接收业务事件。
回调密钥与 AccessKey Secret 用途不同。不能根据收到的请求任意选择外部密钥,也不能把一次普通 HTTP 200 当作已经完成地址验证。
选择事件与来源
| 业务 | 事件 | 收到后查询 |
|---|---|---|
| 签名任务 | signing.succeeded、signing.failed、signing.cancelled、signing.superseded | 原任务状态;成功后查询该任务准确产物。 |
| 上传任务 | upload.completed、upload.failed、upload.cancelled | 原上传任务和版本保存结果。 |
| 版本与发布 | version.ready、distribution.published | 目标版本及当前发布状态。 |
| 订单与额度 | order.paid、refund.completed、capacity.purchased | 原报价或订单回执,按金额单位对账。 |
事件读取需要相应权限,资金通知单独授权。默认来源只涉及本 API 应用发起的操作。各事件的数据含义见事件类型与通知来源。
接收网站操作
网站操作需要独立订阅和授权,来源不能从通知正文推断。根据实际业务选择以下指南。
验签、处理与回执
- HTTP 接入层拒绝重复的签名头,保留未经解析、格式化或转码的原始正文。
- 使用受信订阅配置验证四个签名头、原始正文和时间窗口,确认普通事件的应用归属。
- 普通事件在同一数据库事务内去重并持久保存事件或业务结果。确认此前已经提交的重复事件可返回原回执。
- 事务成功后生成回执,返回 HTTP 2xx 和 JSON。保存失败时返回非 2xx,让平台按规则重投。
可直接下载运行带 SQLite 去重的接收示例。若要集成自己的服务,下面展示验签函数;HTTP 适配和持久事务仍需由自己的框架实现。
在已有 Python 服务中验证通知
from cloudsign.webhook import verify_webhook, acknowledge_webhook
def verify_notification(secret, expected_hook, expected_app, headers, body,
now=None):
if headers["X-Cloudsign-Webhook-Id"] != expected_hook:
raise ValueError("通知不是来自已配置的订阅")
event = verify_webhook(
secret, headers["X-Cloudsign-Webhook-Id"],
headers["X-Cloudsign-Event-Id"], headers["X-Cloudsign-Timestamp"],
body, headers["X-Cloudsign-Signature"], now=now,
)
if event["type"] != "endpoint.challenge":
if event["data"]["app_id"] != expected_app:
raise ValueError("通知应用与订阅配置不符")
return event
# 普通事件:在数据库事务中去重并保存业务结果,提交后再生成回执。
# reply = acknowledge_webhook(secret, verified_event)
# 地址验证事件:验签通过后可直接生成包含 challenge 和 proof 的回执。上方函数只验签和核对归属;调用方需实现自己的持久化事务。保存完成后调用 acknowledge_webhook(secret, verified_event) 生成 JSON 回执。
将验签接入自己的 HTTP 服务
保留上方函数,再使用下面的接收函数。HTTP 层先拒绝重复签名头,将四个签名头映射到示例使用的名称,并传入未经修改的原始字节。commit_once 由自己的数据库实现,按订阅 ID 与事件 ID 建立唯一约束,去重与业务保存放在同一事务内。
def receive_notification(secret, expected_hook, expected_app, headers, body,
commit_once, now=None):
event = verify_notification(secret, expected_hook, expected_app,
headers, body, now=now)
if event["type"] == "endpoint.challenge":
return acknowledge_webhook(secret, event)
# commit_once 由接入程序实现:在同一持久事务中去重并保存业务结果。
# 仅在本次或之前同一事件的事务已提交时返回 True。
if commit_once(expected_hook, event["id"], event) is not True:
raise RuntimeError("业务尚未持久保存,不返回成功回执")
return acknowledge_webhook(secret, event)函数正常返回后,将返回对象序列化为 JSON,以 HTTP 2xx 和 Content-Type: application/json 发回平台。验签或业务保存失败时返回非 2xx;不要捕获异常后仍发送成功回执。已提交的重复事件返回 True 后可再次确认。
普通事件回执为 {"event_id":"<已验证事件ID>"}。地址验证事件还需 challenge 与 proof,使用 SDK 返回的完整对象,不自行删字段。
自行实现 CSWH1 验签
保留四个头:X-Cloudsign-Webhook-Id、X-Cloudsign-Event-Id、X-Cloudsign-Timestamp、X-Cloudsign-Signature。按 LF 连接 CSWH1、订阅 ID、事件 ID、投递时间戳、原始正文 SHA-256,用回调 Secret 计算 HMAC-SHA256,并恒时比较 v1= 签名。允许的投递时间偏差为 300 秒。
普通回执包含 event_id。挑战还需回显 challenge,并对 CSWH1-ACK、订阅 ID、事件 ID、challenge 四行计算 HMAC-SHA256,返回 v1= 开头的 proof。created_at 是事件创建时间,不代替投递时间。
重试、乱序与重放
同一事件重投时保留事件 ID,但投递时间与签名会变化。按受信订阅和事件 ID 去重,不能把旧签名长期缓存为有效授权。
通知到达顺序不保证与操作顺序相同。需要当前状态时,查询原业务资源;超出重放期限或需要长期归档时,使用接收端已经验证并保存的业务记录。
C SDK 接收说明
C SDK 提供 cloudsign_webhook_verify 与 cloudsign_webhook_acknowledge,完整处理步骤和命令行示例见 C SDK 事件接收。数据库去重和 HTTP 服务仍由接入程序实现。