> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subotiz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 事件类型

| **事件名称**  | **事件类型**                                  | **触发时机**                    | **通知数据结构**                                 | 描述                                                                                                                                                                       |
| --------- | ----------------------------------------- | --------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 试用期即将到期通知 | v2.subscription.  trial\_period\_expiring | 试用期剩余时间小于 3 天时，提醒一次         | [Subscription](/zh/webhook/subscription-2) | 用户订阅试用期 3 天后到期 。<br />**使用场景：**<br />到期提醒：向用户推送到期提醒。                                                                                                                     |
| 首次订阅通知    | v2.subscription.first                     | 订阅首次生效时                     | [Subscription](/zh/webhook/subscription-2) | 订阅首次进入**试用期**或者**活跃**状态时通知，每个订阅只会发送一次。<br />**使用场景：**<br />订阅成功推送：发送首次订阅成功的消息（如推送、邮件）<br />权益发放：为用户解锁订阅对应的服务权限（如付费功能、资源额度）                                               |
| 终止订阅通知    | v2.subscription.canceled                  | 订阅终止时                       | [Subscription](/zh/webhook/subscription-2) | 订阅实际终止时通知。<br />**使用场景：**<br />终止服务提示：告知用户订阅已终止，明确服务停止时间<br />权限回收：回收用户付费权益                                                                                              |
| 订阅价格变更    | v2.subscription.price\_changed            | 订阅价格变更时                     | [Subscription](/zh/webhook/subscription-2) | 订阅价格变更时，通知变更具体信息。                                                                                                                                                        |
| 订阅暂停      | v2.subscription.paused                    | 订阅暂停时通知                     | [Subscription](/zh/webhook/subscription-2) | 订阅暂停时通知，用于同步订阅状态。<br />**使用场景：**<br />暂停提醒：告知用户订阅已暂停，服务暂时停止<br />权限调整：暂停用户的订阅权益访问                                                                                        |
| 订阅重启      | v2.subscription.resumed                   | 订阅重启时通知                     | [Subscription](/zh/webhook/subscription-2) | 订阅从暂停状态恢复时通知。<br />**使用场景：**<br />恢复通知：告知用户订阅已重新启用<br />权益恢复：重新开放用户的订阅权益和服务                                                                                              |
| 订阅逾期      | v2.subscription.past\_due                 | 订阅逾期时通知                     | [Subscription](/zh/webhook/subscription-2) | 订阅支付逾期时通知，通常在自动续订扣款失败后进入该状态。<br />**使用场景：**<br />逾期提醒：提醒用户更新支付方式或补缴费用<br />宽限期管理：进入宽限期，限制部分功能但保留数据                                                                       |
| 订阅未支付     | v2.subscription.unpaid                    | 订阅未支付时通知                    | [Subscription](/zh/webhook/subscription-2) | 订阅因长期未支付而被标记为未支付状态时通知。<br />**使用场景：**<br />催款通知：最后一次催促用户完成支付<br />服务限制：暂停或限制用户的订阅服务权限                                                                                    |
| 撤回取消订阅    | v2.subscription.cancellation\_revoked     | 撤回取消订阅时通知                   | [Subscription](/zh/webhook/subscription-2) | 用户撤回之前的取消订阅请求时通知。<br />**使用场景：**<br />状态同步：更新订阅状态为正常，取消之前的终止计划<br />挽留成功提醒：告知用户订阅将继续，确认服务持续                                                                              |
| 请求取消订阅    | v2.subscription.cancellation\_requested   | 请求取消订阅时通知                   | [Subscription](/zh/webhook/subscription-2) | 用户请求取消订阅时通知，但订阅尚未实际终止。<br />**使用场景：**<br />挽留机会：触发用户挽留流程，提供优惠或解决方案<br />状态标记：标记订阅为"待取消"状态，等待周期结束                                                                         |
| 订阅固定期限变更  | v2.subscription.fixed\_term\_updated      | 订阅的固定期限被修改时通知               | [Subscription](/zh/webhook/subscription-2) | 当订阅的固定期限设置发生变更时通知，包括修改期数、切换是否支持到期转续、转为持续订阅等操作。通知数据中包含 `previous_fixed_term_info`，记录变更前的固定期限信息。<br />**使用场景：**<br />状态同步：同步订阅的固定期限变更，更新本地记录<br />业务联动：根据固定期限变更调整用户权益或提醒策略 |
| 账单支付成功    | v2.invoice.paid                           | 一次性商品、首次订阅和订阅续订支付成功时通知      | [Invoice](/zh/webhook/invoice-2)           | 一次性商品和订阅相关的支付成功时会发送该通知。用于同步账单状态、订阅管理。<br />**使用场景：**<br />账单状态同步：更新账单状态为"已完成"；<br />订阅管理：续订账单中会包含订阅周期信息，如当前周期数、周期时间等                                                     |
| 账单支付失败    | v2.invoice.payment\_failed                | 一次性商品、首次订阅和订阅续订支付失败时通知      | [Invoice](/zh/webhook/invoice-2)           | 一次性商品和订阅相关的支付失败时会发送该通知。不会每次重试支付失败都通知，只在最终支付失败时通知。<br />**使用场景：**<br />失败提醒与引导支付：告知用户支付失败，提供重新支付入口                                                                        |
| 账单退款      | v2.invoice.refunded                       | 当订阅产生的交易单退款成功时通知，用于获取订阅退款信息 | [Invoice](/zh/webhook/invoice-2)           | 一次性商品和订阅相关的支付发生退款时会发送该事件。用于同步退款状态。                                                                                                                                       |
| 交易单支付成功   | v2.trades.succeeded                       | 支付成功时                       | [Trade](/zh/webhook/trade-2)               | 所有类型的支付成功时会发送该通知，适用于纯金额交易的闭环。                                                                                                                                            |
| 交易单支付失败   | v2.trades.payment\_failed                 | 支付失败时                       | [Trade](/zh/webhook/trade-2)               | 所有类型的支付失败时会发送该通知，适用于纯金额交易的闭环。                                                                                                                                            |
| 退款成功      | v2.refunds.succeeded                      | 退款成功时                       | [Refund](/zh/webhook/refund-2)             | 退款实际完成时通知。<br />**使用场景：**<br />退款通知与状态同步：告知用户退款金额，更新退款单状态为"已完成"                                                                                                          |
| 退款失败      | v2.refunds.failed                         | 退款失败时                       | [Refund](/zh/webhook/refund-2)             | 退款实际失败时通知<br />**使用场景：**<br />状态同步：更新退款单状态为“失败"<br />重试与人工干预：触发自动重试机制，或通知客服人工排查，及时重新发起退款，避免用户投诉和资金纠纷。                                                                    |
| 争议创建通知    | v2.disputes.created                       | 争议首次创建时                     | [Dispute](/zh/webhook/dispute-2)           | 渠道首次回传争议数据时通知，每个 `channel_dispute_id` 仅发送一次。<br />**使用场景：**<br />争议入账：在商户系统中创建对应争议工单<br />资金提示：根据 `dispute_amount` 在结算视图中标记冻结金额                                          |
| 争议更新通知    | v2.disputes.updated                       | 争议关键字段变化时                   | [Dispute](/zh/webhook/dispute-2)           | 已存在的争议在状态、原因、金额或截止时间等关键字段发生变化时通知。<br />**使用场景：**<br />状态同步：根据 `dispute_status` 更新本地争议状态<br />抗辩提醒：根据 `dispute_due_time` 推送商户证据提交提醒                                       |