
主要功能
Real-time Delivery
Secure by Default
Automatic Retries
Event Filtering
入门
Access Webhook Settings
Developer > Webhooks。Create Webhook Endpoint
Add Webhook 以创建新的 webhook 端点。
Add Endpoint URL
Select Events to Receive
Get Secret Key
Secret Key。您将使用它来验证收到的 webhooks 的真实性。Rotate Secret (Optional)
配置订阅事件
您可以配置每个 webhook 端点想要接收的具体事件。访问事件配置
Navigate to Webhook Details
Developer > Webhooks。Select Your Endpoint
Open Event Settings
管理事件订阅
View Available Events
dispute,payment,subscription)。Search and Filter
Select Events
- 选择单个子事件(例如,
dispute.accepted,dispute.challenged) - 选择父事件以接收所有相关的子事件
- 根据您的需求混合和匹配特定事件
Review Event Details
Save Configuration
Webhook 传递
超时
Webhooks 对连接和读取操作有一个 15 秒的超时窗口。确保您的端点快速响应以避免超时。自动重试
如果 webhook 传递失败,Dodo Payments 会自动重试并进行指数退避,以防止系统超负荷。幂等性
每个 webhook 事件都包含一个唯一的webhook-id 头。使用此标识符实现幂等性以防止重复处理。
事件排序
Webhook 事件可能由于重试或网络条件而无序到达。设计您的系统将能够处理任何顺序的事件。保护 Webhooks
为了确保您的 webhooks 的安全性,请始终验证有效负载并使用 HTTPS。验证签名
每个 webhook 请求都包含一个webhook-signature 头,即 webhook 有效负载和时间戳的 HMAC SHA256 签名,使用您的密钥签名。
SDK 验证(推荐)
所有官方 SDK 都包括内置助手,用于安全验证和解析传入的 webhooks。提供两种方法:unwrap(): 使用您的 webhook 秘密密钥验证签名unsafe_unwrap(): 解析有效负载而不进行验证
手动验证(替代方案)
如果您不使用 SDK,您可以按照 Standard Webhooks 规范自行验证签名:- 通过用点(
.)分隔webhook-id、webhook-timestamp和准确的原始字符串化payload来构建签名消息。 - 使用仪表板中的 webhook 秘密密钥计算该字符串的 HMAC SHA256。
- 将计算出的签名与
webhook-signature头进行比较。如果它们匹配,webhook 是可信的。
响应 Webhooks
- 您的 webhook 处理程序必须返回一个
2xx status code以确认收到事件。 - 任何其他响应将被视为失败,webhook 将被重试。
最佳实践
Use HTTPS endpoints only
Use HTTPS endpoints only
Respond immediately
Respond immediately
200 状态码。异步处理事件以避免超时。Handle duplicate events
Handle duplicate events
webhook-id 头实现幂等性,以安全地多次处理相同事件而不产生副作用。Secure your webhook secret
Secure your webhook secret
Webhook 有效负载结构
了解 webhook 有效负载结构有助于您正确解析和处理事件。请求格式
头
请求正文
payment.succeeded,subscription.active)。示例负载
Event Types
Event Payloads
Handle Payment Failures
payment.failed 并恢复被拒付款测试 Webhooks
您可以直接从 Dodo Payments 仪表板测试您的 webhook 集成,以确保您的端点在上线前正常工作。
访问测试界面
Navigate to Webhooks
Developer > Webhooks。Select Your Endpoint
Open Testing Tab
测试您的 Webhook
测试界面提供了一种全面的方法来测试您的 webhook 端点:Select Event Type
payment.succeeded,payment.failed,等)。Review Schema and Example
Send Test Event
验证您的测试
Check Your Endpoint
Verify Signature
Test Response
2xx 状态码以确认收到。实现示例
以下是展示 webhook 验证和处理的完整 Express.js 实现:使用 CLI 测试 Webhooks
Dodo Payments CLI 提供了两条命令,用于在本地开发期间测试 webhooks,而无需离开您的终端。本地监听实时 Webhooks
将实际 webhook 事件从您的测试模式帐户实时转发到您的本地开发服务器:http://localhost:3000/webhook),保留包括签名头在内的所有头部以用于验证测试。
dodo login 并选择测试模式,然后使用此命令。触发模拟 Webhook 事件
将模拟 webhook 负载发送到任何端点,而无需创建实际交易:CLI Webhook Testing Docs
高级设置
高级设置选项卡提供了用于微调 webhook 端点行为的附加配置选项。速率限制(节流)
控制向您的端点传递 webhook 事件的速度,以防止系统超负荷。Access Rate Limit Settings
Configure Rate Limit
Set Limits
自定义头
将自定义 HTTP 头添加到所有发送到您的端点的 webhook 请求。这对于认证、路由或向您的 webhook 请求中添加元数据非常有用。Add Custom Header
Add Multiple Headers
Save Configuration
转换
转换允许您修改 webhook 的有效负载并将其重定向到不同的 URL。此强大功能使您能够:- 在处理前修改有效负载结构
- 根据内容将 webhooks 路由到不同的端点
- 从有效负载中添加或删除字段
- 转换数据格式
Enable Transformations
Configure Transformation
Test Transformation
监控 Webhook 日志
日志选项卡提供了对 webhook 传递状态的全面可见性,使您能够有效监控、调试和管理 webhook 事件。
活动监控
活动选项卡提供了实时的 webhook 传递性能洞察和可视化分析。
电子邮件提醒
通过自动电子邮件通知保持了解 webhook 的状态。当 webhook 传递开始失败或您的端点停止响应时,您将收到电子邮件提醒,以便您可以快速解决问题并保持集成顺利运行。
启用电子邮件提醒
Navigate to Alerting Settings
Enable Email Notifications
Configure Email Address