Skip to main content
Webhook Cover Image
Webhooks 在 Dodo Payments 账户中发生特定事件时提供实时通知。使用 webhooks 来自动化工作流程、更新数据库、发送通知,并保持系统同步。
我们的 webhook 实现遵循 Standard Webhooks 规范,确保与行业最佳实践和现有 webhook 库兼容。

主要功能

Real-time Delivery

当事件发生时接收即时通知

Secure by Default

包括 HMAC SHA256 签名验证

Automatic Retries

内置重试逻辑,具有指数退避

Event Filtering

仅订阅您需要的事件

入门

1

Access Webhook Settings

导航到 DodoPayments 仪表板并转到 Developer > Webhooks
2

Create Webhook Endpoint

单击 Add Webhook 以创建新的 webhook 端点。
Add Webhook
3

Add Endpoint URL

输入您想要接收 webhook 事件的 URL。
4

Select Events to Receive

通过从事件列表中选择特定事件来选择您的 webhook 端点应监听的事件。
只有选定的事件会触发发送到您的端点的 webhooks,帮助您避免不必要的流量和处理。
5

Get Secret Key

从设置页面获取您的 webhook Secret Key。您将使用它来验证收到的 webhooks 的真实性。
确保您的 webhook 秘密密钥安全,绝不要在客户端代码或公共存储库中公开。
6

Rotate Secret (Optional)

如果需要,您可以旋转您的 webhook 密钥以增强安全性。在您的 webhook 设置中单击 旋转密钥 按钮。
旋转密钥将 过期它 并用新的替换它。旧密钥在接下来的 24 小时内有效。之后,尝试用旧密钥验证将失败。
定期使用密钥旋转或在怀疑当前密钥已被泄露时立即使用。

配置订阅事件

您可以配置每个 webhook 端点想要接收的具体事件。

访问事件配置

1

Navigate to Webhook Details

前往 Dodo Payments 仪表板并导航到 Developer > Webhooks
2

Select Your Endpoint

单击您要配置的 webhook 端点。
3

Open Event Settings

在 webhook 详细信息页面中,您将看到“订阅事件”部分。单击 编辑 按钮以修改您的事件订阅。

管理事件订阅

1

View Available Events

界面显示所有可用的 webhook 事件,以分层结构组织。事件按类别分组(例如,disputepaymentsubscription)。
2

Search and Filter

使用搜索栏通过输入事件名称或关键字快速找到特定事件。
3

Select Events

勾选要接收的事件旁边的框。您可以:
  • 选择单个子事件(例如,dispute.accepteddispute.challenged
  • 选择父事件以接收所有相关的子事件
  • 根据您的需求混合和匹配特定事件
4

Review Event Details

将鼠标悬停在每个事件旁边的信息图标(ⓘ)上,查看该事件何时触发的描述。
5

Save Configuration

单击 保存 以应用您的更改,或单击 取消 以放弃修改。
如果取消选择所有事件,您的 webhook 端点将不会收到任何通知。确保至少选择您的应用程序正常运行所需的事件。

Webhook 传递

超时

Webhooks 对连接和读取操作有一个 15 秒的超时窗口。确保您的端点快速响应以避免超时。
通过立即用 200 状态码确认接收来异步处理 webhooks,然后在后台处理实际处理。

自动重试

如果 webhook 传递失败,Dodo Payments 会自动重试并进行指数退避,以防止系统超负荷。
每个 webhook 事件最多 8 次重试。例如,如果一个 webhook 在成功之前失败了三次,那么从第一次尝试到最终成功的总传递时间大约是 35 分钟 5 秒。
使用 Dodo Payments 仪表板手动重试个别消息或在任何时候批量恢复所有失败的消息。

幂等性

每个 webhook 事件都包含一个唯一的 webhook-id 头。使用此标识符实现幂等性以防止重复处理。
始终实现幂等性检查。由于重试,您可能会多次收到相同事件。

事件排序

Webhook 事件可能由于重试或网络条件而无序到达。设计您的系统将能够处理任何顺序的事件。
无论 webhook 事件最初何时发出,您都会在交付时收到最新的有效负载

保护 Webhooks

为了确保您的 webhooks 的安全性,请始终验证有效负载并使用 HTTPS。

验证签名

每个 webhook 请求都包含一个 webhook-signature 头,即 webhook 有效负载和时间戳的 HMAC SHA256 签名,使用您的密钥签名。

SDK 验证(推荐)

所有官方 SDK 都包括内置助手,用于安全验证和解析传入的 webhooks。提供两种方法:
  • unwrap(): 使用您的 webhook 秘密密钥验证签名
  • unsafe_unwrap(): 解析有效负载而不进行验证
在初始化 Dodo Payments 客户端时,通过 DODO_PAYMENTS_WEBHOOK_KEY 提供您的 webhook 密钥。

手动验证(替代方案)

如果您不使用 SDK,您可以按照 Standard Webhooks 规范自行验证签名:
  1. 通过用点(.)分隔 webhook-idwebhook-timestamp 和准确的原始字符串化 payload 来构建签名消息。
  2. 使用仪表板中的 webhook 秘密密钥计算该字符串的 HMAC SHA256。
  3. 将计算出的签名与 webhook-signature 头进行比较。如果它们匹配,webhook 是可信的。
我们遵循 Standard Webhooks 规范。您可以使用他们的库来验证签名:https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries。对于事件有效负载格式,请参见 Webhook Payload

响应 Webhooks

  • 您的 webhook 处理程序必须返回一个 2xx status code 以确认收到事件。
  • 任何其他响应将被视为失败,webhook 将被重试。

最佳实践

始终使用 HTTPS URL 作为 webhook 端点。HTTP 端点容易遭受中间人攻击并暴露您的 webhook 数据。
在接收 webhook 时立即返回一个 200 状态码。异步处理事件以避免超时。
使用 webhook-id 头实现幂等性,以安全地多次处理相同事件而不产生副作用。
使用环境变量或密钥管理器安全存储您的 webhook 密钥。切勿将密钥提交到版本控制。

Webhook 有效负载结构

了解 webhook 有效负载结构有助于您正确解析和处理事件。

请求格式

string
必填
此 webhook 事件的唯一标识符。用于幂等性检查。
string
必填
用于验证 webhook 真实性的 HMAC SHA256 签名。
string
必填
发送 webhook 时的 Unix 时间戳(以秒为单位)。

请求正文

string
必填
您的 Dodo Payments 业务标识符。
string
必填
触发此 webhook 的事件类型(例如,payment.succeededsubscription.active)。
string
必填
事件发生时的 ISO 8601 格式时间戳。
object
必填
事件特定有效负载,包含有关事件的详细信息。

示例负载

Event Types

浏览所有可用 webhook 事件类型

Event Payloads

查看每个事件的详细有效负载模式

Handle Payment Failures

响应 payment.failed 并恢复被拒付款

测试 Webhooks

您可以直接从 Dodo Payments 仪表板测试您的 webhook 集成,以确保您的端点在上线前正常工作。
Endpoint Details

访问测试界面

1

Navigate to Webhooks

前往 Dodo Payments 仪表板并导航到 Developer > Webhooks
2

Select Your Endpoint

单击您的 webhook 端点以访问其详细信息页面。
3

Open Testing Tab

单击 测试 选项卡以访问 webhook 测试界面。

测试您的 Webhook

测试界面提供了一种全面的方法来测试您的 webhook 端点:
1

Select Event Type

使用下拉菜单选择要测试的特定事件类型(例如,payment.succeededpayment.failed,等)。
下拉列表包含您的端点可以接收的所有可用 webhook 事件类型。
2

Review Schema and Example

界面显示所选事件类型的 模式 (数据结构)和 示例 (示例负载)。
3

Send Test Event

单击 发送示例 按钮向您的端点发送测试 webhook。
重要提示:通过测试界面发送的失败消息不会重试。此仅用于测试目的。

验证您的测试

1

Check Your Endpoint

监控您的 webhook 端点日志以确认测试事件已收到。
2

Verify Signature

确保您的签名验证与测试有效负载正常工作。
3

Test Response

确认您的端点返回一个 2xx 状态码以确认收到。

实现示例

以下是展示 webhook 验证和处理的完整 Express.js 实现:
在处理生产事件之前,使用仪表板上的测试界面对您的 webhook 处理程序进行彻底测试。这有助于及早识别和修复问题。

使用 CLI 测试 Webhooks

Dodo Payments CLI 提供了两条命令,用于在本地开发期间测试 webhooks,而无需离开您的终端。

本地监听实时 Webhooks

将实际 webhook 事件从您的测试模式帐户实时转发到您的本地开发服务器:
CLI 打开一个与 Dodo Payments 的 WebSocket 连接,并将每个 webhook 事件转发到您的本地端点(例如,http://localhost:3000/webhook),保留包括签名头在内的所有头部以用于验证测试。
监听器仅适用于 测试模式 API 密钥。运行 dodo login 并选择测试模式,然后使用此命令。

触发模拟 Webhook 事件

将模拟 webhook 负载发送到任何端点,而无需创建实际交易:
此交互式工具允许您从所有支持的事件类型中进行选择,并将真实感的模拟负载发送到您的端点。它会循环,因此您可以在一个会话中测试多个事件。
来自 dodo wh trigger 的模拟 webhook 负载未签名。在测试期间,在您的 webhook 处理程序中使用 unsafe_unwrap() 代替 unwrap()

CLI Webhook Testing Docs

查看完整的 CLI webhook 测试文档

高级设置

高级设置选项卡提供了用于微调 webhook 端点行为的附加配置选项。

速率限制(节流)

控制向您的端点传递 webhook 事件的速度,以防止系统超负荷。
1

Access Rate Limit Settings

高级 选项卡中,找到“速率限制(节流)”部分。
2

Configure Rate Limit

单击 编辑 按钮修改速率限制设置。
默认情况下,webhooks 没有应用“速率限制”,这意味着事件在发生时立即传递。
3

Set Limits

配置您所需的速率限制以控制 webhook 传递频率并防止系统过载。
当您的 webhook 处理程序需要时间处理事件或您希望将多个事件打包在一起时,请使用速率限制。

自定义头

将自定义 HTTP 头添加到所有发送到您的端点的 webhook 请求。这对于认证、路由或向您的 webhook 请求中添加元数据非常有用。
1

Add Custom Header

在“自定义头”部分,输入您的自定义头的
2

Add Multiple Headers

单击 + 按钮根据需要添加其他自定义头。
3

Save Configuration

您的自定义头将包含在所有发送到此端点的 webhook 请求中。

转换

转换允许您修改 webhook 的有效负载并将其重定向到不同的 URL。此强大功能使您能够:
  • 在处理前修改有效负载结构
  • 根据内容将 webhooks 路由到不同的端点
  • 从有效负载中添加或删除字段
  • 转换数据格式
1

Enable Transformations

切换 启用 开关以激活转换功能。
2

Configure Transformation

单击 编辑转换 以定义您的转换规则。
您可以使用 JavaScript 转换 webhook 有效负载并指定不同的目标 URL。
3

Test Transformation

使用测试界面验证您的转换是否在上线前正常工作。
转换可能对 webhook 传递性能产生重大影响。请彻底测试并保持转换逻辑简单高效。
转换特别适用于:
  • 在不同数据格式之间转换
  • 根据特定标准过滤事件
  • 向有效负载添加计算字段
  • 将事件路由到不同的微服务

监控 Webhook 日志

日志选项卡提供了对 webhook 传递状态的全面可见性,使您能够有效监控、调试和管理 webhook 事件。
Logs

活动监控

活动选项卡提供了实时的 webhook 传递性能洞察和可视化分析。
Activity

电子邮件提醒

通过自动电子邮件通知保持了解 webhook 的状态。当 webhook 传递开始失败或您的端点停止响应时,您将收到电子邮件提醒,以便您可以快速解决问题并保持集成顺利运行。
Webhook Alerting Settings showing email notifications configuration

启用电子邮件提醒

1

Navigate to Alerting Settings

前往 Dodo Payments 仪表板并导航至 仪表板 → Webhooks → 提醒
2

Enable Email Notifications

切换 电子邮件通知 开关,以开始接收有关 webhook 传递问题的提醒。
3

Configure Email Address

输入您想要接收 webhook 提醒的电子邮件地址。当您的 webhooks 设置发生某些事件时,例如可能影响您的集成的传递问题,我们将向此地址发送通知。
启用电子邮件提醒以尽早发现 webhook 传递问题并维护可靠的集成。您将在传递失败或端点无法响应时收到通知。

部署到云平台

准备好将您的 webhook 处理程序部署到生产环境了吗?我们提供了平台特定的指南,帮助您将 webhooks 部署到流行的云提供商,并提供每个平台的最佳实践。

Vercel

使用无服务器功能将 webhooks 部署到 Vercel

Cloudflare Workers

在 Cloudflare 的边缘网络上运行 webhooks

Supabase Edge Functions

与 Supabase 集成 webhooks

Netlify Functions

作为 Netlify 无服务器功能部署 webhooks
每个平台指南包括特定于该提供商的环境设置、签名验证和部署步骤。

相关 API 参考

Create Webhook

用于以编程方式创建和配置 webhook 端点的 API 参考

List Webhooks

用于检索和管理您的 webhook 端点的 API 参考
最后修改于 2026年7月21日