
主要功能
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 是有效的。
响应 Webhooks
- 您的 webhook handler 必须返回
2xx status code,以确认收到 event。 - 任何其他 response 都会被视为失败,并且 webhook 将被重试。
最佳实践
Use HTTPS endpoints only
Use HTTPS endpoints only
Respond immediately
Respond immediately
200 status code。异步处理 event,以避免超时。Handle duplicate events
Handle duplicate events
webhook-id header 实现幂等性,从而安全地多次处理同一个 event 且不产生副作用。Secure your webhook secret
Secure your webhook secret
Webhook Payload Structure
了解 webhook payload structure 有助于正确解析和处理 events。Request Format
Headers
Request Body
payment.succeeded、subscription.active)。示例 Payload
Event Types
Event Payloads
Handle Payment Failures
payment.failed 并恢复 declined payments测试 Webhooks
您可以直接从 Dodo Payments dashboard 测试 webhook integration,确保 endpoint 在上线前正常工作。Navigate to Webhooks
Select Your Endpoint
Open Testing Tab
发送示例 Event
Testing 标签页会向此 endpoint 发送示例 payload,方便您验证 receiver。Select Event Type
payment.succeeded 或 payment.failed。Send Example
Check Your Endpoint
2xx status code。Implementation Example
以下是一个完整的 Express.js implementation,展示 webhook verification 和 handling:使用 CLI 测试 Webhooks
Dodo Payments CLI 提供两个命令,用于在 local development 期间测试 webhooks,无需离开 terminal。在本地监听 Live Webhooks
实时将 test mode account 的真实 webhook events 转发到本地 development server:http://localhost:3000/webhook),同时保留包括 signature headers 在内的所有 headers,以便进行 verification testing。
dodo login,并在使用此命令前选择 Test Mode。触发 Mock Webhook Events
向任意 endpoint 发送 mock webhook payloads,无需创建真实 transactions:CLI Webhook Testing Docs
Advanced Settings
Advanced 标签页提供额外的 configuration options,用于精细调整 webhook endpoint behavior。Rate Limiting(Throttling)
控制 webhook events 发送到 endpoint 的速率,避免系统过载。Open Advanced Tab
Configure Rate Limit
Set Your Limit
自定义 Headers
向发送到 endpoint 的所有 webhook requests 添加自定义 HTTP headers。这对于 authentication、routing 或添加 metadata 很有用。Add Headers
Add Multiple Headers
Transformations
Transformations 允许您修改 webhook payload,并可选择将其重定向到其他 URL。此强大功能可以:- 在处理前修改 payload structure
- 根据内容将 webhooks 路由到不同 endpoints
- 从 payload 添加或移除 fields
- 转换 data formats
Enable Transformations
Configure Transformation
Test Transformation
监控 Webhook Logs
Logs 标签页全面展示 webhook delivery status,帮助您有效监控、调试和管理 webhook events。Navigate to Logs Tab
Browse Delivery History
Search and Filter
View Message Details
- 完整的 webhook payload
- 每次 delivery attempt 及其 response code 和 duration
- 每次 attempt 的 timestamp
- endpoint 返回的任何 error messages
Activity Monitoring
进入 Developer → Webhooks,打开 Activity 标签页,查看所有 endpoints 的 delivery performance。 Delivery activity 会按时间绘制 attempts;根据时间窗口,分组方式为 Attempts per 5 minutes、Attempts per hour 或 Attempts per day。每个柱状条会按 outcome 拆分,悬停在某个分段上可查看 status、attempts 数量及其占总数的比例。在 endpoint 中,Overview 标签页的 Delivery stats (last 24h) 会汇总过去一天的相同信息。Replay 和恢复 Messages
重新驱动 message 的方式取决于需要处理的数量:- 一条 message — 从 Logs 标签页打开它,并在 attempt 上使用 Replay 操作。无需打开 endpoint。
- 一系列 messages — 打开 endpoint,因为批量模式每次只作用于一个 endpoint。
批量 Replay
从 Developer → Webhooks 打开 endpoint。共有三种模式,每种模式仅作用于该 endpoint。您设置的范围取决于所选模式:Open More Actions
Set the Range
Start the Run
Email Alerts
当发送到某个 endpoint 的 webhook deliveries 失败时接收 email notification,以便在问题形成积压之前及时处理。Navigate to Settings Tab
Find Email Alerting
Configure Email Addresses
Save