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

Webhook 事件类型与通知来源

本页内容

选择业务需要的事件和通知来源,理解各类事件携带的资源 ID,再按原资源核对结果。本页说明签名、上传、发布和资金通知的区别。

按业务选择事件

只订阅您的程序需要处理的事件。通知用于触发后续查询,不能代替业务资源的当前状态,也不保证只发送一次。地址验证另用 endpoint.challenge,它不属于下表的业务订阅项。

事件表示什么收到后做什么
signing.succeeded签名任务成功。查询原任务及准确产物,再申请下载凭证。
signing.failed签名任务失败。读取原任务的失败原因,不另建任务掩盖失败。
signing.cancelled签名任务已取消。结束对该任务的等待。
signing.superseded任务已被后续处理替代。核对原任务状态和当前有效任务,不使用旧产物。
upload.completedAPI 上传任务完成。查询原上传任务,取得保存的原包版本。
upload.failedAPI 上传任务失败。查询失败原因和可恢复状态。
upload.cancelledAPI 上传任务已取消。结束该次上传流程。
version.ready安装包校验成功且版本已保存。读取该版本;企业签名仍需另行开通和签名。
distribution.published普通分发版本已发布。读取当前发布状态与下载设置。
order.paid购买订单已付款。核对原报价和订单回执。
refund.completed原订单已退款。核对退款回执及被撤销的权益。
capacity.purchased安装量扩容已购买。核对扩容回执和当前权益。

查询签名结果用 查询签名任务对应的准确产物;查询上传用 查询上传任务。版本与发布用 查询指定版本和 读取分发下载页设置。付款、退款和扩容分别见订单对账与企业签名费用与退款。

确定通知来自哪些操作

通知来源在创建订阅时选定,请与订阅 ID、应用 ID 和回调密钥一同保存到受信配置。正文不带 source_scope 来源字段;不能根据事件名称推断它来自 API 还是网站。

api 表示当前 API 应用发起的已授权操作;website 表示网站普通分发历史版本发布;website_upload 表示网站更新已有普通分发安装包。后两类需要独立授权,具体步骤如下。

选择通知来源

默认订阅接收当前 API 应用发起的操作。需要接收在网站上完成的普通分发操作时,请另建订阅并选择对应来源。网站通知功能需先为账号开通。

要接收的操作通知来源可选事件
通过 API 完成的操作API 应用上方事件表中已授权的事件
在网站切换或回滚普通分发历史版本网站历史版本发布distribution.published
在网站更新已有普通分发应用的安装包网站更新上传version.ready、distribution.published

订阅网站历史版本发布

  1. 确认账号已开通“网站普通分发历史版本发布通知”。
  2. 在开发者中心,为接收通知的 API 应用授予 distribution:ReadWebsiteEvents 和 distribution:ReadPublicationEvents,资源范围选择要订阅的自有应用。
  3. 新建 Webhook,来源选择“网站历史版本发布”,填写完整应用 ID,勾选 distribution.published。保存回调密钥并完成接收地址验证。
  4. 在网站切换到另一个历史版本。接收端验签、去重并持久保存后,返回接收回执。

事件 data.resource_id 是本次发布的版本 ID,previous_version_id 是切换前的版本 ID。首次发布时,后者为 null。再次选择当前有效版本不会产生新通知。

网站发布事件的 data
{
    "app_id": "A11111111111111111111111111111111",
    "resource_id": "V22222222222222222222222222222222",
    "status": "published",
    "previous_version_id": "V33333333333333333333333333333333"
}

订阅网站更新上传

  1. 确认账号已开通“网站普通分发更新上传通知”。这项功能需单独开通。
  2. 授予 API 应用 distribution:ReadWebsiteUploadEvents。选择 version.ready 还需 distribution:ReadVersionEvents;选择 distribution.published 还需 distribution:ReadPublicationEvents。
  3. 新建 Webhook,来源选择“网站更新上传”(website_upload),填写已有应用 ID,选择事件并完成接收地址验证。
  4. 在网站更新该应用的 IPA 或 APK。安装包校验成功并保存版本后发送通知;文件传输完成但版本尚未保存时不会发送。
网站更新上传事件的 data
{
    "app_id": "A11111111111111111111111111111111",
    "resource_id": "V22222222222222222222222222222222",
    "status": "ready",
    "upload_id": "U44444444444444444444444444444444"
}
如何使用通知中的上传任务 ID

此来源的 upload_id 用于关联网站上传记录,不能用于调用 API 上传任务的查询、恢复或取消接口。收到通知后,请使用 app_id 和 resource_id 查询应用及版本。

通知范围与授权变化
  • 网站更新上传来源只覆盖已有普通分发应用的现代浏览器上传流程。首次新建、旧式上传回调、企业签名和超级签名上传不在此来源的范围内。
  • 已有订阅不会自动接收新来源;订阅前的操作不补发。通知只涉及已授权的自有应用,总代理权限不自动包含下级账号。
  • 通知权限不包含上传、修改或发布权限。账号、API 应用、功能开通或资源授权被撤销后,尚未发出的通知停止;已发出的请求无法撤回。
  • 通知可能重复或乱序。按已验证的订阅 ID 和事件 ID 去重,并查询业务资源确认当前状态。

留存与重放

版本与发布事件的留存时间由平台配置,为 90–365 天,默认为 90 天。延长留存时间无法恢复已清理的事件。需要长期保存时,请在接收端验签后保存自己的业务记录。

失败通知可在创建后七天内人工重放,最多三轮;每轮自动重试最多八次,并在 24 小时内结束。留存时间与重放时间分别计算。SDK 的验签与回执助手可用于上述全部通知来源。

理解事件数据

以下字段均位于已验签正文的 data 对象中。除 previous_version_id 可以为 null 外,各类列出的字段均存在。不要仅凭 ID 前缀把资源传给其他类型的接口。

签名与 API 上传

字段类型说明
app_idstring业务应用 ID(A)。与受信订阅绑定的应用一致。
resource_idstring签名事件为签名任务 ID(J);上传事件为 API 上传任务 ID(U)。
statusstring与事件对应的任务状态。upload.completed 的状态值为 succeeded;其他任务事件使用名称末段的状态值。

版本就绪与普通分发发布

字段类型说明
app_id / resource_idstring分别是业务应用 ID(A)与本次版本 ID(V)。
statusstring版本就绪为 ready,发布为 published。
upload_idstring仅版本就绪事件包含,表示关联上传 ID(U)。网站来源的 ID 仅用于关联,不能调用 API 上传恢复接口。
previous_version_idstring | null仅发布事件包含,表示上次发布的版本 ID(V);首次发布可以为 null。

付款、退款与扩容

字段类型说明
app_idstring业务应用 ID(A)。
resource_idstring订单 ID(O)。退款通知也使用原订单 ID,不是退款回执 ID。
quote_idstring关联报价 ID(Q)。
statusstring付款和扩容为 paid,退款为 refunded。
amountstring保留两位小数的金额文本,与原交易核对。
currency_codestring原交易的金额单位代码。
currency_revisionstring原交易的金额单位修订号。不要改用当前站点单位或自行换算。

资金事件不返回当前余额。请查询原回执及账户流水进行对账,不因收到通知再次充值、付款或退款。

金额与单位的精确约束

金额为非负十进制字符串,整数部分最多 9 位,小数固定 2 位。单位代码为 CNY、USD、EUR、HKD、GBP、POINT 或 CUSTOM。修订号为 C 后接 64 位小写十六进制字符。展示名称和符号从原交易的单位信息获取。

地址验证

endpoint.challenge 的 data 只有 challenge,为 64 位小写十六进制挑战值。它没有 app_id、resource_id 或 status,按端点验证回执处理。

保存事件并查询结果

  1. 根据受信订阅选择回调密钥,验证原始正文和应用归属。
  2. 以 (webhook_id, id) 建立唯一约束,在同一事务中保存事件或完成业务处理。
  3. 确认提交后返回回执。后续查询使用通知中的完整资源 ID,不使用列表第一项代替。
  4. 重复事件不重复执行业务;乱序事件不直接覆盖较新的状态。需要当前状态时重新查询资源。

可从Python 接收示例开始验证接入,再把已保存事件交给自己的后台业务。