Webhook 事件指南

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.paused`	订阅暂停时触发。
订阅已恢复	`subscription.unpaused`	暂停的订阅恢复时触发。
订阅已续订	`subscription.renewed`	订阅成功续订时发生。
订阅计划已更改	`subscription.plan_changed`	订阅升级、降级或修改为包含不同附加项时触发。
订阅支付方式已更新	`subscription.update_payment_method`	订阅的支付方式更新时发送。携带 Subscription payload。
订阅已取消	`subscription.cancelled`	订阅被商家或客户取消时触发。
订阅失败	`subscription.failed`	表示订阅失败。这意味着我们无法创建 mandate。
订阅已过期	`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。

信用事件

事件名称	事件类型	描述
信用添加	`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。

催款事件

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

有关详细的有效载荷架构、字段说明和处理程序示例，请参阅恢复 Webhooks。

Payout 事件

这些事件跟踪您的资金从 Dodo Payments 转入银行账户的过程，与 dashboard 中显示的 payout 状态相对应。payload 是一个 payout object，其结构与 GET /payouts 中的条目相同。

事件名称	事件类型	描述
Payout 已创建	`payout.created`	当 payout 通过 automatic payout cycle 或非周期流程创建时触发。
Payout 处理中	`payout.in_progress`	当 payout 到期日到达并开始处理时发生。
Payout 暂停处理	`payout.on_hold`	当 payout 暂停或进入审核时触发。
Payout 成功	`payout.success`	当向银行账户发起的 payout 成功处理时发生。
Payout 失败	`payout.failed`	当 payout 失败时触发。资金和费用会退回您的 wallet。

请勿假设 payout 事件是终态事件或严格按顺序排列。payout.failed 可能会在 payout.success 之后正常到达，例如银行退回转账时；而当失败的 payout 后续得到恢复时，payout.success 也可能在 payout.failed 之后到达。始终将 payload 上的状态视为当前状态。

payout.created 之前以 payout.not_initiated 的形式发送。如果您已有基于 payout.not_initiated 进行过滤的 endpoint，请将 filter 更新为 payout.created，以便其继续匹配。

有关详细的 payload schema、字段说明和 handler 示例，请参阅 Payout Webhooks。这些 webhook 事件旨在向商户提供关键更新，帮助其有效管理运营。请在 webhook integration 中为每个相关事件实现健壮的 handler，以确保功能平稳可靠。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

支付事件

退款事件

争议事件

订阅事件

许可证密钥事件

权限授予事件

信用事件

恢复事件

催款事件

Payout 事件

​支付事件

​退款事件

​争议事件

​订阅事件

​许可证密钥事件

​权限授予事件

​信用事件

​恢复事件

​催款事件

​Payout 事件

支付事件

退款事件

争议事件

订阅事件

许可证密钥事件

权限授予事件

信用事件

恢复事件

催款事件

Payout 事件