
主要功能
Real-time Delivery
Secure by Default
Automatic Retries
Event Filtering
入门
- 位于 Developer → Webhooks 下 — Endpoints、Event catalog、Logs、Activity 和 Settings 标签页。
- 位于单个 endpoint 中 — Overview 标签页,其中包含 delivery stats、signing secret 和 Replay history,以及 Testing 和 Advanced 标签页与批量 replay 操作。
- 位于消息中 — 从 Logs 标签页打开;您可以单独 replay 每次 delivery attempt,无需打开 endpoint。
Access Webhook Settings
Create Webhook Endpoint
Enter Endpoint URL or Choose Integration
Select Events to Receive
Create Endpoint
Get Secret Key
Rotate Secret (Optional)
Integration Connectors
您无需自行构建 webhook receiver,也可以使用 integration connectors 将 webhook events 直接路由到第三方服务。这样便无需为常见平台编写和维护自定义 webhook handlers。Connectors 的工作方式
Connector 会执行转换,将 Dodo Payments event 转换为目标服务所需的格式。您需要提供的详细信息取决于目标服务:设置 Connector
创建或编辑 endpoint 时选择一个 connector,侧边面板会显示针对该目标服务编写的设置说明,例如如何在 Slack 中创建 incoming webhook URL,或在哪里查找 Resend API key。保存前,请运行 connector transformation test,以确认 event 已正确转换为目标服务所需的格式。配置订阅的 Events
您可以配置每个 webhook endpoint 应接收的具体 events。Navigate to Webhook Endpoints
Select Your Endpoint
Open Event Configuration
Browse Event Types
payment、subscription、dispute)。使用搜索栏可按名称或关键字快速查找特定 events。Select Events
- 选择单个 events(例如
payment.succeeded、payment.failed) - 选择父级 resource 以接收所有相关 events
- 根据需求混合选择特定 events
Save Configuration
Event Catalog
进入 Developer → Webhooks,打开 Event catalog 标签页。该页面列出了 Dodo Payments 可以发送的所有 event types,方便您在为 endpoint 订阅 event 前了解可用内容。选择某个 event 可查看其 schema 和示例 payload,这是检查您计划读取的字段格式最快的方式。Webhook Events Guide
Webhook Delivery
超时
Webhooks 对 connection 和 read operations 均设有 15 秒超时窗口。请确保 endpoint 快速响应,以避免超时。自动重试
如果 webhook delivery 失败,Dodo Payments 会自动采用 exponential backoff 进行重试,以避免系统过载。幂等性
每个 webhook event 都包含唯一的webhook-id header。使用此标识符实现幂等性,防止重复处理。
Event Ordering
由于重试或网络状况,Webhook events 可能会乱序到达。请设计系统,使其能够按任意顺序处理 events。保护 Webhooks
为确保 webhooks 的安全性,请始终验证 payloads 并使用 HTTPS。验证 Signatures
每个 webhook request 都包含webhook-signature header,该 header 是 webhook payload 和 timestamp 的 HMAC SHA256 signature,并使用您的 secret key 进行签名。
SDK verification(推荐)
所有官方 SDK 都内置了用于安全验证和解析传入 webhooks 的 helpers。有两种方法可用:unwrap():使用 webhook secret key 验证 signaturesunsafe_unwrap():不验证 signatures,直接解析 payloads
手动 verification(替代方案)
如果您不使用 SDK,可以按照 Standard Webhooks spec 自行验证 signatures:- 将
webhook-id、webhook-timestamp和精确的原始字符串化payload用句点(.)连接,构建 signed message。 - 使用 Dashboard 中的 webhook secret key,计算该字符串的 HMAC SHA256。
- 将计算出的 signature 与
webhook-signatureheader 进行比较。如果匹配,则 webhook 是有效的。
源 IP 地址
Signature verification 是支持的 webhook 身份验证方式。它可以证明请求使用了您的 webhook secret 签名,而网络层检查无法做到这一点。 Webhook 交付来自属于我们交付基础设施的源 IP 地址池。该地址池会不时变化,因此应将这些地址视为运营细节,而不是集成的固定属性。 如果您的基础设施位于要求显式 allowlist 的防火墙之后,请注意以下事项:- 不要永久硬编码地址。 地址范围会随着时间推移不断添加和弃用,过时的规则会悄无声息地阻止交付。
- 请求当前地址范围:在锁定防火墙之前,请通过 support@dodopayments.com 获取当前地址范围,确保使用的是最新列表。
- 留意变更通知。 交付地址发生变化时,我们会通过电子邮件通知受影响的商户 — 请在指定日期前应用这些更新,以避免交付丢失。
- 无论添加了哪些网络规则,都要保持 Signature verification 启用。
响应 Webhook
- 您的 webhook handler 必须返回
2xx status code,以确认已收到事件。 - 任何其他响应都会被视为失败,webhook 将被重试。
最佳实践
Use HTTPS endpoints only
Use HTTPS endpoints only
Respond immediately
Respond immediately
200 status code。请异步处理事件,以避免超时。Handle duplicate events
Handle duplicate events
webhook-id header 实现幂等性,从而安全地多次处理同一事件而不会产生副作用。Secure your webhook secret
Secure your webhook secret
Webhook Payload 结构
了解 webhook payload 结构有助于您正确解析和处理事件。Request 格式
Headers
Request Body
payment.succeeded、subscription.active)。Payload 示例
Event Types
Event Payloads
Handle Payment Failures
payment.failed 并恢复被拒付的款项测试 Webhook
您可以直接从 Dodo Payments dashboard 测试 webhook 集成,以确保 endpoint 在上线前正常工作。Navigate to Webhooks
Select Your Endpoint
Open Testing Tab
发送示例事件
Testing tab 会向此 endpoint 发送示例 payload,以便您验证 receiver。Select Event Type
payment.succeeded 或 payment.failed。Send Example
Check Your Endpoint
2xx status code。实现示例
下面是一个完整的 Express.js 实现,展示了 webhook verification 和处理:使用 CLI 测试 Webhook
Dodo Payments CLI 提供两个命令,可在本地开发期间测试 webhook,无需离开 terminal。在本地监听实时 Webhook
实时将 test mode account 的真实 webhook 事件转发到本地开发服务器:http://localhost:3000/webhook),同时保留包括 signature headers 在内的所有 headers,以便进行验证测试。
dodo login,并在使用此命令前选择 Test Mode。触发模拟 Webhook 事件
向任意 endpoint 发送模拟 webhook payload,而无需创建真实交易:CLI Webhook Testing Docs
高级设置
Advanced tab 提供其他配置选项,用于微调 webhook endpoint 的行为。Rate Limiting(Throttling)
控制 webhook 事件交付到 endpoint 的速率,防止系统过载。Open Advanced Tab
Configure Rate Limit
Set Your Limit
自定义 Headers
向发送到 endpoint 的所有 webhook requests 添加自定义 HTTP headers。这对于身份验证、路由或添加 metadata 很有用。Add Headers
Add Multiple Headers
Transformations
Transformations 允许您修改 webhook 的 payload,并可选择将其重定向到其他 URL。此强大功能可以帮助您:- 在处理前修改 payload 结构
- 根据内容将 webhook 路由到不同 endpoint
- 从 payload 中添加或删除字段
- 转换数据格式
Enable Transformations
Configure Transformation
Test Transformation
监控 Webhook Logs
Logs tab 提供 webhook 交付状态的全面可见性,帮助您有效监控、调试和管理 webhook 事件。Navigate to Logs Tab
Browse Delivery History
Search and Filter
View Message Details
- 完整的 webhook payload
- 每次交付尝试及其 response code 和 duration
- 每次尝试的 timestamp
- endpoint 返回的任何错误消息
Activity Monitoring
前往 Developer → Webhooks,然后打开 Activity tab,查看各 endpoint 的交付性能。 Delivery activity 按时间绘制尝试次数,并根据时间窗口分组为 Attempts per 5 minutes、Attempts per hour 或 Attempts per day。每个柱状条会按结果拆分,将鼠标悬停在某个部分上即可查看状态、尝试次数及其占总数的比例。在 endpoint 的 Overview tab 中,Delivery stats (last 24h) 会汇总过去一天的相同信息。重新发送和恢复消息
重新驱动消息的方式取决于您需要处理的消息数量:- 一条消息 — 从 Logs tab 打开消息,并使用该尝试上的 Replay 操作。无需打开 endpoint。
- 一批消息 — 打开 endpoint,因为批量模式一次只作用于一个 endpoint。
批量重新发送
从 Developer → Webhooks 打开 endpoint。共有三种模式,每种模式只作用于该 endpoint。设置的范围取决于所选模式:Open More Actions
Set the Range
Start the Run
Email Alerts
当向某个 endpoint 的 webhook 交付失败时接收电子邮件通知,以便在问题形成积压之前及时处理。Navigate to Settings Tab
Find Email Alerting
Configure Email Addresses
Save