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

# Webhook 事件指南

> 了解不同的 webhook 事件。这些事件由 Dodo Payments 在付款、退款、订阅、争议、许可证密钥、权限授予、信用、恢复和催款活动期间触发

Dodo Payments 提供实时 webhook 通知，以便您了解与交易、订阅、退款、争议和许可证密钥管理相关的关键事件。以下是这些事件的详细指南，按类别分类以便于理解，并附有实施提示和注意事项。

## **支付事件**

| **事件名称**  | **事件类型**             | **描述**                 |
| --------- | -------------------- | ---------------------- |
| **支付成功**  | `payment.succeeded`  | 当付款成功处理时触发。            |
| **支付失败**  | `payment.failed`     | 付款尝试因错误、被拒卡或其他问题失败时发生。 |
| **支付处理中** | `payment.processing` | 表示付款正在处理中。             |
| **支付已取消** | `payment.cancelled`  | 付款在完成前被取消时触发。          |

## **退款事件**

| **事件名称** | **事件类型**           | **描述**               |
| -------- | ------------------ | -------------------- |
| **退款成功** | `refund.succeeded` | 退款成功处理时触发。           |
| **退款失败** | `refund.failed`    | 退款尝试因处理错误或其他问题失败时发生。 |

## **争议事件**

| **事件名称** | **事件类型**             | **描述**          |
| -------- | -------------------- | --------------- |
| **争议开启** | `dispute.opened`     | 当客户发起争议时触发。     |
| **争议过期** | `dispute.expired`    | 表示争议在未解决的情况下过期。 |
| **争议接受** | `dispute.accepted`   | 当商户接受争议时触发。     |
| **争议取消** | `dispute.cancelled`  | 当客户或系统取消争议时发生。  |
| **争议质疑** | `dispute.challenged` | 当商户对争议提出质疑时触发。  |
| **争议胜诉** | `dispute.won`        | 表示商户已成功赢得争议。    |
| **争议败诉** | `dispute.lost`       | 当商户在争议中失败时发生。   |

## **订阅事件**

| **事件名称**   | **事件类型**                    | **描述**                   |
| ---------- | --------------------------- | ------------------------ |
| **订阅激活**   | `subscription.active`       | 表示订阅已激活并且计划进行定期收费。       |
| **订阅更新**   | `subscription.updated`      | 当任何订阅字段更新时触发（无需轮询的实时同步）。 |
| **订阅暂停**   | `subscription.on_hold`      | 当订阅因续订失败而暂时暂停时触发。        |
| **订阅续订**   | `subscription.renewed`      | 当订阅成功续订时发生。              |
| **订阅计划变更** | `subscription.plan_changed` | 当订阅升级、降级或添加不同插件时触发。      |
| **订阅取消**   | `subscription.cancelled`    | 当商户或客户取消订阅时触发。           |
| **订阅失败**   | `subscription.failed`       | 表示订阅失败，这意味着我们无法创建授权。     |
| **订阅过期**   | `subscription.expired`      | 当订阅达到期限并过期时触发。           |

## **许可证密钥事件**

| **事件名称**   | **事件类型**              | **描述**             |
| ---------- | --------------------- | ------------------ |
| **许可密钥创建** | `license_key.created` | 当为某个产品创建新的许可密钥时触发。 |

## **权限授予事件**

| **事件名称** | **事件类型**                      | **描述**                                                                                   |
| -------- | ----------------------------- | ---------------------------------------------------------------------------------------- |
| **授予创建** | `entitlement_grant.created`   | 为客户创建新的权限授予。许可证密钥授予通过 `delivered` 到达；基于 OAuth 的授予（Discord、GitHub、Notion）通过 `pending` 到达。 |
| **授予交付** | `entitlement_grant.delivered` | 授予履行完成—许可证密钥已发放、文件链接已解析或平台访问已授予。                                                         |
| **授予失败** | `entitlement_grant.failed`    | 授予履行失败；检查 `error_code` 和 `error_message`。                                                |
| **授予撤销** | `entitlement_grant.revoked`   | 访问被撤销；检查 `revocation_reason` （订阅状态、退款、计划变更或手动）。                                          |

有关详细的有效载荷架构、示例事件和完整的 `revocation_reason` 参考，请参阅[权限授予 Webhooks](/developer-resources/webhooks/intents/entitlement-grant)。

## **信用事件**

| **事件名称** | **事件类型**                    | **描述**                      |
| -------- | --------------------------- | --------------------------- |
| **信用添加** | `credit.added`              | 当授予客户信用（订阅、一次性、附加或 API）时触发。 |
| **信用扣除** | `credit.deducted`           | 当通过使用或手动借记消费信用时发生。          |
| **信用过期** | `credit.expired`            | 当未使用的信用在配置的过期周期后过期时触发。      |
| **信用结转** | `credit.rolled_over`        | 当未使用的信用在周期结束时被结转到新的授予时发生。   |
| **结转没收** | `credit.rollover_forfeited` | 当达到最大结转次数时，触发信用被没收事件。       |
| **超额费用** | `credit.overage_charged`    | 当因超额使用而应用超额费用时发生。           |
| **手动调整** | `credit.manual_adjustment`  | 当进行手动信用或借记调整时触发。            |
| **余额低**  | `credit.balance_low`        | 当信用余额低于配置阈值时触发。             |

## **恢复事件**

| **事件名称**    | **事件类型**                       | **描述**                    |
| ----------- | ------------------------------ | ------------------------- |
| **放弃的结账检测** | `abandoned_checkout.detected`  | 当检测到不完整或失败的结账超过 60 分钟时触发。 |
| **放弃的结账恢复** | `abandoned_checkout.recovered` | 当客户通过恢复链接完成付款时发生。         |

有关详细的负载架构、字段描述和处理程序示例，请参见 [恢复 Webhooks](/developer-resources/webhooks/intents/recovery)。

## **催款事件**

| **事件名称** | **事件类型**            | **描述**                   |
| -------- | ------------------- | ------------------------ |
| **催款开始** | `dunning.started`   | 当对处于保留或取消状态的订阅开始催款尝试时触发。 |
| **催款恢复** | `dunning.recovered` | 当客户更新其付款方式并成功扣款时发生。      |

有关详细的有效载荷架构、字段说明和处理程序示例，请参阅[恢复 Webhooks](/developer-resources/webhooks/intents/recovery)。

这些 webhook 事件旨在为商家提供重要更新，以有效管理其运营。在您的 webhook 集成中为每个相关事件实施稳健的处理程序，以确保功能顺畅和可靠。