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

接收 Webhook 事件通知

本页内容

平台可在上传、签名、发布或订单状态变化后,向您配置的 HTTPS 地址发送通知。接收端需要验签、去重并在业务保存成功后返回回执。

了解通知流程

  1. 配置订阅
  2. 验证接收地址
  3. 接收并验证事件
  4. 持久保存并确认

Webhook 用于减少轮询,最终业务状态仍以资源查询为准。通知可能重复或乱序;接收端需要按事件 ID 去重,不能只按 HTTP 请求到达次数处理业务。

首次接入可先运行Python 接收示例;已有 HTTP 服务时,按报文与回执参考接入验签和持久事务。

创建订阅并验证地址

  1. 在开发者中心选中自己的 API 应用,确认通知功能和所需事件权限已开放。
  2. 填写 HTTPS 接收地址,绑定业务应用并选择事件及来源。
  3. 保存独立的回调密钥,配置接收端的受信订阅 ID 与应用 ID。
  4. 处理 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 应用发起的操作。各事件的数据含义见事件类型与通知来源。

接收网站操作

网站操作需要独立订阅和授权,来源不能从通知正文推断。根据实际业务选择以下指南。

验签、处理与回执

  1. HTTP 接入层拒绝重复的签名头,保留未经解析、格式化或转码的原始正文。
  2. 使用受信订阅配置验证四个签名头、原始正文和时间窗口,确认普通事件的应用归属。
  3. 普通事件在同一数据库事务内去重并持久保存事件或业务结果。确认此前已经提交的重复事件可返回原回执。
  4. 事务成功后生成回执,返回 HTTP 2xx 和 JSON。保存失败时返回非 2xx,让平台按规则重投。

可直接下载运行带 SQLite 去重的接收示例。若要集成自己的服务,下面展示验签函数;HTTP 适配和持久事务仍需由自己的框架实现。

在已有 Python 服务中验证通知
Python SDK
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 建立唯一约束,去重与业务保存放在同一事务内。

Python SDK
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 服务仍由接入程序实现。