> ## 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.

# 事件类型

| **事件名称**  | **事件类型**                               | **触发时机**                    | **通知数据结构**                                 | 描述                                                                                                                         |
| --------- | -------------------------------------- | --------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| 试用期即将到期通知 | subscription.  trial\_period\_expiring | 试用期剩余时间小于 3 天时，提醒一次         | [Subscription](/zh/webhook/subscription-1) | 用户订阅试用期 3 天后到期 。<br />**使用场景：**<br />到期提醒：向用户推送到期提醒。                                                                       |
| 首次订阅通知    | subscription.first                     | 订阅首次生效时                     | [Subscription](/zh/webhook/subscription-1) | 订阅首次进入**试用期**或者**活跃**状态时通知，每个订阅只会发送一次。<br />**使用场景：**<br />订阅成功推送：发送首次订阅成功的消息（如推送、邮件）<br />权益发放：为用户解锁订阅对应的服务权限（如付费功能、资源额度） |
| 终止订阅通知    | subscription.canceled                  | 订阅终止时                       | [Subscription](/zh/webhook/subscription-1) | 订阅实际终止时通知。<br />**使用场景：**<br />终止服务提示：告知用户订阅已终止，明确服务停止时间<br />权限回收：回收用户付费权益                                                |
| 订阅价格变更    | subscription.price\_changed            | 订阅价格变更时                     | [Subscription](/zh/webhook/subscription-1) | 订阅价格变更时，通知变更具体信息。                                                                                                          |
| 账单支付成功    | invoice.paid                           | 一次性商品、首次订阅和订阅续订支付成功时通知      | [Invoice](/zh/webhook/invoice)             | 一次性商品和订阅相关的支付成功时会发送该通知。用于同步账单状态、订阅管理。<br />**使用场景：**<br />账单状态同步：更新账单状态为"已完成"；<br />订阅管理：续订账单中会包含订阅周期信息，如当前周期数、周期时间等       |
| 账单支付失败    | invoice.payment\_failed                | 一次性商品、首次订阅和订阅续订支付失败时通知      | [Invoice](/zh/webhook/invoice)             | 一次性商品和订阅相关的支付失败时会发送该通知。不会每次重试支付失败都通知，只在最终支付失败时通知。<br />**使用场景：**<br />失败提醒与引导支付：告知用户支付失败，提供重新支付入口                          |
| 账单退款      | invoice.refunded                       | 当订阅产生的交易单退款成功时通知，用于获取订阅退款信息 | [Invoice](/zh/webhook/invoice)             | 一次性商品和订阅相关的支付发生退款时会发送该事件。用于同步退款状态。                                                                                         |
| 交易单支付成功   | trades.succeeded                       | 支付成功时                       | [Trade](/zh/webhook/trade-1)               | 所有类型的支付成功时会发送该通知，适用于纯金额交易的闭环。                                                                                              |
| 交易单支付失败   | trades.payment\_failed                 | 支付失败时                       | [Trade](/zh/webhook/trade-1)               | 所有类型的支付失败时会发送该通知，适用于纯金额交易的闭环。                                                                                              |
| 退款成功      | refunds.succeeded                      | 退款成功时                       | [Refund](/zh/webhook/refund-1)             | 退款实际完成时通知。<br />**使用场景：**<br />退款通知与状态同步：告知用户退款金额，更新退款单状态为"已完成"                                                            |
| 退款失败      | refunds.failed                         | 退款失败时                       | [Refund](/zh/webhook/refund-1)             | 退款实际失败时通知<br />**使用场景：**<br />状态同步：更新退款单状态为“失败"<br />重试与人工干预：触发自动重试机制，或通知客服人工排查，及时重新发起退款，避免用户投诉和资金纠纷。                      |