Webhook 事件类型与通知来源
本页内容
选择业务需要的事件和通知来源,理解各类事件携带的资源 ID,再按原资源核对结果。本页说明签名、上传、发布和资金通知的区别。
按业务选择事件
只订阅您的程序需要处理的事件。通知用于触发后续查询,不能代替业务资源的当前状态,也不保证只发送一次。地址验证另用 endpoint.challenge,它不属于下表的业务订阅项。
| 事件 | 表示什么 | 收到后做什么 |
|---|---|---|
signing.succeeded | 签名任务成功。 | 查询原任务及准确产物,再申请下载凭证。 |
signing.failed | 签名任务失败。 | 读取原任务的失败原因,不另建任务掩盖失败。 |
signing.cancelled | 签名任务已取消。 | 结束对该任务的等待。 |
signing.superseded | 任务已被后续处理替代。 | 核对原任务状态和当前有效任务,不使用旧产物。 |
upload.completed | API 上传任务完成。 | 查询原上传任务,取得保存的原包版本。 |
upload.failed | API 上传任务失败。 | 查询失败原因和可恢复状态。 |
upload.cancelled | API 上传任务已取消。 | 结束该次上传流程。 |
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 |
订阅网站历史版本发布
- 确认账号已开通“网站普通分发历史版本发布通知”。
- 在开发者中心,为接收通知的 API 应用授予
distribution:ReadWebsiteEvents和distribution:ReadPublicationEvents,资源范围选择要订阅的自有应用。 - 新建 Webhook,来源选择“网站历史版本发布”,填写完整应用 ID,勾选
distribution.published。保存回调密钥并完成接收地址验证。 - 在网站切换到另一个历史版本。接收端验签、去重并持久保存后,返回接收回执。
事件 data.resource_id 是本次发布的版本 ID,previous_version_id 是切换前的版本 ID。首次发布时,后者为 null。再次选择当前有效版本不会产生新通知。
{
"app_id": "A11111111111111111111111111111111",
"resource_id": "V22222222222222222222222222222222",
"status": "published",
"previous_version_id": "V33333333333333333333333333333333"
}订阅网站更新上传
- 确认账号已开通“网站普通分发更新上传通知”。这项功能需单独开通。
- 授予 API 应用
distribution:ReadWebsiteUploadEvents。选择version.ready还需distribution:ReadVersionEvents;选择distribution.published还需distribution:ReadPublicationEvents。 - 新建 Webhook,来源选择“网站更新上传”(
website_upload),填写已有应用 ID,选择事件并完成接收地址验证。 - 在网站更新该应用的 IPA 或 APK。安装包校验成功并保存版本后发送通知;文件传输完成但版本尚未保存时不会发送。
{
"app_id": "A11111111111111111111111111111111",
"resource_id": "V22222222222222222222222222222222",
"status": "ready",
"upload_id": "U44444444444444444444444444444444"
}此来源的 upload_id 用于关联网站上传记录,不能用于调用 API 上传任务的查询、恢复或取消接口。收到通知后,请使用 app_id 和 resource_id 查询应用及版本。
通知范围与授权变化
- 网站更新上传来源只覆盖已有普通分发应用的现代浏览器上传流程。首次新建、旧式上传回调、企业签名和超级签名上传不在此来源的范围内。
- 已有订阅不会自动接收新来源;订阅前的操作不补发。通知只涉及已授权的自有应用,总代理权限不自动包含下级账号。
- 通知权限不包含上传、修改或发布权限。账号、API 应用、功能开通或资源授权被撤销后,尚未发出的通知停止;已发出的请求无法撤回。
- 通知可能重复或乱序。按已验证的订阅 ID 和事件 ID 去重,并查询业务资源确认当前状态。
留存与重放
版本与发布事件的留存时间由平台配置,为 90–365 天,默认为 90 天。延长留存时间无法恢复已清理的事件。需要长期保存时,请在接收端验签后保存自己的业务记录。
失败通知可在创建后七天内人工重放,最多三轮;每轮自动重试最多八次,并在 24 小时内结束。留存时间与重放时间分别计算。SDK 的验签与回执助手可用于上述全部通知来源。
理解事件数据
以下字段均位于已验签正文的 data 对象中。除 previous_version_id 可以为 null 外,各类列出的字段均存在。不要仅凭 ID 前缀把资源传给其他类型的接口。
签名与 API 上传
| 字段 | 类型 | 说明 |
|---|---|---|
app_id | string | 业务应用 ID(A)。与受信订阅绑定的应用一致。 |
resource_id | string | 签名事件为签名任务 ID(J);上传事件为 API 上传任务 ID(U)。 |
status | string | 与事件对应的任务状态。upload.completed 的状态值为 succeeded;其他任务事件使用名称末段的状态值。 |
版本就绪与普通分发发布
| 字段 | 类型 | 说明 |
|---|---|---|
app_id / resource_id | string | 分别是业务应用 ID(A)与本次版本 ID(V)。 |
status | string | 版本就绪为 ready,发布为 published。 |
upload_id | string | 仅版本就绪事件包含,表示关联上传 ID(U)。网站来源的 ID 仅用于关联,不能调用 API 上传恢复接口。 |
previous_version_id | string | null | 仅发布事件包含,表示上次发布的版本 ID(V);首次发布可以为 null。 |
付款、退款与扩容
| 字段 | 类型 | 说明 |
|---|---|---|
app_id | string | 业务应用 ID(A)。 |
resource_id | string | 订单 ID(O)。退款通知也使用原订单 ID,不是退款回执 ID。 |
quote_id | string | 关联报价 ID(Q)。 |
status | string | 付款和扩容为 paid,退款为 refunded。 |
amount | string | 保留两位小数的金额文本,与原交易核对。 |
currency_code | string | 原交易的金额单位代码。 |
currency_revision | string | 原交易的金额单位修订号。不要改用当前站点单位或自行换算。 |
资金事件不返回当前余额。请查询原回执及账户流水进行对账,不因收到通知再次充值、付款或退款。
金额与单位的精确约束
金额为非负十进制字符串,整数部分最多 9 位,小数固定 2 位。单位代码为 CNY、USD、EUR、HKD、GBP、POINT 或 CUSTOM。修订号为 C 后接 64 位小写十六进制字符。展示名称和符号从原交易的单位信息获取。
地址验证
endpoint.challenge 的 data 只有 challenge,为 64 位小写十六进制挑战值。它没有 app_id、resource_id 或 status,按端点验证回执处理。
保存事件并查询结果
- 根据受信订阅选择回调密钥,验证原始正文和应用归属。
- 以
(webhook_id, id)建立唯一约束,在同一事务中保存事件或完成业务处理。 - 确认提交后返回回执。后续查询使用通知中的完整资源 ID,不使用列表第一项代替。
- 重复事件不重复执行业务;乱序事件不直接覆盖较新的状态。需要当前状态时重新查询资源。
可从Python 接收示例开始验证接入,再把已保存事件交给自己的后台业务。