Webhooks 在您的 Dodo Payments 账户中,当特定事件发生时提供实时通知。使用 webhooks 自动化工作流程、更新数据库、发送通知并保持系统同步。
主要特性
Real-time Delivery
在事件发生时立即接收通知
Secure by Default
包含 HMAC SHA256 签名验证
Automatic Retries
内置指数回退重试逻辑
开始使用
Access Webhook Settings
进入 DodoPayments 仪表板并前往 Settings > Webhooks。
Create Webhook Endpoint
点击 Add Webhook 以创建新的 webhook 端点。 Add Endpoint URL
输入要接收 webhook 事件的 URL。
Select Events to Receive
从事件列表中选择特定事件,让 webhook 端点监听这些事件。只有所选事件会触发发送到您的端点的 webhook,帮助您避免不必要的流量和处理。
Get Secret Key
在设置页面获取您的 webhook Secret Key。您将用它来验证接收到的 webhook 的真实性。妥善保管您的 webhook 密钥,切勿在客户端代码或公开仓库中泄露。
Rotate Secret (Optional)
如有必要,可轮换 webhook 密钥以提升安全性。在 webhook 设置中点击 Rotate Secret 按钮。轮换密钥会使其失效并替换为新密钥。旧密钥在接下来的 24 小时内仍然有效。之后使用旧密钥验证将失败。
配置订阅事件
您可以为每个 webhook 端点配置希望接收的特定事件。
访问事件配置
Navigate to Webhook Details
进入 Dodo Payments 仪表板并前往 Settings > Webhooks。
Select Your Endpoint
点击要配置的 webhook 端点。
Open Event Settings
在 webhook 详情页面,您会看到“Subscribed events”部分。点击 Edit 按钮修改事件订阅。
管理事件订阅
View Available Events
界面以分层结构显示所有可用的 webhook 事件。事件按类别分组(例如 dispute、payment、subscription)。
Search and Filter
使用搜索栏通过输入事件名称或关键字快速查找特定事件。
Select Events
勾选您想接收的事件旁的复选框。您可以:
- 选择单个子事件(例如
dispute.accepted、dispute.challenged)
- 选择父事件以接收所有相关子事件
- 根据需求混合选择特定事件
Review Event Details
将鼠标悬停在每个事件旁的提示图标(ⓘ)上,即可查看该事件触发的描述。
Save Configuration
点击 Save 应用更改,或点击 Cancel 放弃修改。
如果取消选择所有事件,您的 webhook 端点将不会收到任何通知。请确保至少选择应用正常运行所需的事件。
Webhook 交付
Webhook 的 15 秒超时窗口 适用于连接和读取操作。确保您的端点快速响应以避免超时。
通过立即返回 200 状态码确认接受 webhook,然后在后台异步处理实际逻辑。
自动重试
如果 webhook 交付失败,Dodo Payments 会自动以指数退避的方式重试,以防止对您的系统造成过大压力。
| 尝试 | 延迟 | 描述 |
|---|
| 1 | 立即 | 第一次重试立即发生 |
| 2 | 5 秒 | 第二次尝试在短暂延迟后进行 |
| 3 | 5 分钟 | 第三次尝试增加退避 |
| 4 | 30 分钟 | 第四次尝试继续退避 |
| 5 | 2 小时 | 第五次尝试延长延迟 |
| 6 | 5 小时 | 第六次尝试更长延迟 |
| 7 | 10 小时 | 第七次尝试最大延迟 |
| 8 | 10 小时 | 最后一次尝试 - 如果不成功,webhook 将标记为失败 |
每个 webhook 事件最多重试 8 次。例如,如果一个 webhook 在成功之前失败三次,则从第一次尝试开始的总投递时间约为 35 分 5 秒。
使用 Dodo Payments 仪表板手动重试单条消息或批量恢复所有失败消息。
幂等性
每个 webhook 事件都包含唯一的 webhook-id 标头。使用该标识符实现幂等性,防止重复处理。
// Example: Storing webhook IDs to prevent duplicate processing
const processedWebhooks = new Set();
app.post('/webhook', (req, res) => {
const webhookId = req.headers['webhook-id'];
if (processedWebhooks.has(webhookId)) {
return res.status(200).json({ received: true });
}
processedWebhooks.add(webhookId);
// Process the webhook...
});
始终实现幂等性检查。由于重试机制,您可能会收到相同事件的多次发送。
事件顺序
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 密钥。
import DodoPayments from 'dodopayments';
import express from 'express';
const app = express();
app.use(express.raw({ type: 'application/json' }));
const client = new DodoPayments({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
});
app.post('/webhook', async (req, res) => {
try {
const unwrapped = client.webhooks.unwrap(req.body.toString(), {
headers: {
'webhook-id': req.headers['webhook-id'] as string,
'webhook-signature': req.headers['webhook-signature'] as string,
'webhook-timestamp': req.headers['webhook-timestamp'] as string,
},
});
res.json({ received: true });
} catch (error) {
res.status(401).json({ error: 'Invalid signature' });
}
});
手动验证(替代)
如果您不使用 SDK,您可以按照 Standard Webhooks 规范自行验证签名:
- 构建签名消息:将
webhook-id、webhook-timestamp 与精确的原始字符串化 payload 通过点号 (.) 连接。
- 使用仪表板中的 webhook 密钥计算该字符串的 HMAC SHA256 值。
- 将计算出的签名与
webhook-signature 标头进行比对。如果匹配,则 webhook 为真实请求。
响应 Webhooks
- 您的 webhook 处理程序必须返回
2xx status code,以确认已收到事件。
- 其他任何响应都将被视为失败,webhook 会被重试。
最佳实践
始终为 webhook 端点使用 HTTPS URL。HTTP 端点容易受到中间人攻击,并会暴露您的 webhook 数据。
使用 webhook-id 标头实现幂等性,以安全地多次处理相同事件而不会带来副作用。
Secure your webhook secret
使用环境变量或密钥管理器安全存储 webhook 密钥。切勿将密钥提交到版本控制。
Webhook 有效负载结构
了解 webhook 有效负载结构有助于您正确解析和处理事件。
请求格式
POST /your-webhook-url
Content-Type: application/json
该 webhook 事件的唯一标识符。用于幂等性检查。
用于验证 webhook 真伪的 HMAC SHA256 签名。
发送 webhook 的 Unix 时间戳(以秒为单位)。
请求体
触发此 webhook 的事件类型(例如 payment.succeeded、subscription.active)。
包含事件详细信息的特定有效负载。显示 Data object properties
资源类型:Payment、Subscription、Refund、Dispute 或 LicenseKey。
附加字段因事件类型而异。完整架构请参阅事件特定文档。
示例有效负载
{
"business_id": "string",
"type": "payment.succeeded | payment.failed |...",
"timestamp": "2024-01-01T12:00:00Z",
"data": {
"payload_type": "Payment | Subscription | Refund | Dispute | LicenseKey",
// ... event-specific fields (see below)
}
}
测试 Webhooks
您可以直接从 Dodo Payments 仪表板测试您的 webhook 集成,以确保您的端点正常工作,然后再上线。
访问测试界面
Navigate to Webhooks
进入 Dodo Payments 仪表板并前往 Settings > Webhooks。
Select Your Endpoint
点击您的 webhook 端点,进入其详情页面。
Open Testing Tab
点击 Testing 选项卡以访问 webhook 测试界面。
测试您的 Webhook
测试界面提供了一种全面的方式来测试您的 webhook 端点:
Select Event Type
使用下拉菜单选择要测试的特定事件类型(例如 payment.succeeded、payment.failed 等)。下拉列表包含端点可以接收的所有可用 webhook 事件类型。
Review Schema and Example
界面同时显示所选事件类型的 Schema(数据结构)和 Example(示例有效负载)。
Send Test Event
点击 Send Example 按钮向您的端点发送测试 webhook。注意:通过测试界面发送的失败消息不会被重试,仅用于测试用途。
验证您的测试
Check Your Endpoint
监控 webhook 端点日志以确认测试事件是否已接收。
Verify Signature
使用测试有效负载验证您的签名验证是否正常工作。
Test Response
确认您的端点返回 2xx 状态码以确认已接收。
实现示例
以下是一个完整的 Express.js 实现,展示了 webhook 验证和处理:
import { Webhook } from "standardwebhooks";
import express from "express";
const app = express();
app.use(express.json());
const webhook = new Webhook(process.env.DODO_WEBHOOK_SECRET);
app.post('/webhook/dodo-payments', async (req, res) => {
try {
// Extract webhook headers
const webhookHeaders = {
"webhook-id": req.headers["webhook-id"] as string,
"webhook-signature": req.headers["webhook-signature"] as string,
"webhook-timestamp": req.headers["webhook-timestamp"] as string,
};
// Verify the webhook signature
const payload = JSON.stringify(req.body);
await webhook.verify(payload, webhookHeaders);
// Acknowledge receipt immediately
res.status(200).json({ received: true });
// Process webhook asynchronously
processWebhookAsync(req.body).catch(console.error);
} catch (error) {
console.error('Webhook verification failed:', error);
res.status(400).json({ error: 'Invalid signature' });
}
});
async function processWebhookAsync(data: any) {
// Handle the webhook event based on type
switch (data.type) {
case 'payment.succeeded':
await handlePaymentSucceeded(data);
break;
case 'subscription.active':
await handleSubscriptionActive(data);
break;
// Add more event handlers...
}
}
在处理生产事件前,请通过仪表板测试界面彻底测试 webhook 处理程序。这有助于及早发现并解决问题。
使用 CLI 测试 Webhooks
Dodo Payments CLI 提供两个命令,用于在本地开发中测试 webhooks,无需离开终端。
在本地监听实时 Webhooks
将测试模式账户的实时 webhook 事件转发到本地开发服务器:
CLI 会打开与 Dodo Payments 的 WebSocket 连接,并将每个 webhook 事件转发到本地端点(例如 http://localhost:3000/webhook),保留所有标头,包括用于验证的签名标头。
监听器仅适用于测试模式 API 密钥。运行 dodo login 并选择测试模式后再使用该命令。
触发模拟 Webhook 事件
向任意端点发送模拟 webhook 有效负载,而无需创建真实交易:
此交互式工具让您从 22 种受支持的事件类型中进行选择,并将真实感的模拟有效负载发送至您的端点。它会循环运行,因此您可以在一个会话中测试多个事件。
来自 dodo wh trigger 的模拟 webhook 有效负载不带签名。测试期间请使用 unsafe_unwrap() 替代 unwrap()。
CLI Webhook Testing Docs
查看完整的 CLI webhook 测试文档
高级设置
高级设置选项卡提供更多配置选项,便于微调 webhook 端点行为。
速率限制(节流)
控制 webhook 事件发送到端点的频率,防止系统过载。
Access Rate Limit Settings
在Advanced 选项卡中找到“Rate Limit (throttling)”部分。
Configure Rate Limit
点击 Edit 按钮以修改速率限制设置。默认情况下,webhook 设置为“不限速”,即事件发生时立即投递。
Set Limits
配置所需的速率限制,以控制 webhook 投递频率并防止系统过载。
当 webhook 处理程序需要时间处理事件或想要将多个事件批量处理时,请使用速率限制。
自定义标头
为发送到端点的所有 webhook 请求添加自定义 HTTP 标头。这对于身份验证、路由或添加元数据非常有用。
Add Custom Header
在“Custom Headers”部分输入自定义标头的键和值。
Add Multiple Headers
点击 + 按钮以根据需要添加其他自定义标头。
Save Configuration
您的自定义标头将包含在发送到此端点的所有 webhook 请求中。
转换允许您修改 webhook 的有效负载并将其重定向到不同的 URL。该强大功能可实现:
- 在处理前修改有效负载结构
- 根据内容将 webhook 路由到不同端点
- 添加或删除有效负载字段
- 转换数据格式
Enable Transformations
切换 Enabled 开关以启用转换功能。
Configure Transformation
点击 Edit transformation 以定义转换规则。您可以使用 JavaScript 转换 webhook 有效负载并指定不同的目标 URL。
Test Transformation
使用测试界面验证转换在上线前是否正常工作。
转换可能显著影响 webhook 投递性能。请充分测试并保持转换逻辑简洁高效。
转换特别适用于:
- 在不同数据格式之间转换
- 根据特定条件筛选事件
- 向有效负载添加计算字段
- 将事件路由到不同的微服务
监控 Webhook 日志
Logs 选项卡提供全面的 webhook 投递状态可见性,帮助您有效监控、调试和管理 webhook 事件。
活动监控
Activity 选项卡通过可视化分析提供 webhook 投递性能的实时洞察。
邮件提醒
通过自动邮件通知随时了解 webhook 健康状况。当 webhook 投递开始失败或端点停止响应时,您会收到邮件提醒,便于快速排查问题并保持集成稳定运行。
启用邮件提醒
Navigate to Alerting Settings
进入 Dodo Payments 仪表板,导航至 Dashboard → Webhooks → Alerting。
Enable Email Notifications
打开 Email notifications 开关以开始接收 webhook 投递问题提醒。
Configure Email Address
输入希望接收 webhook 警报的邮箱地址。当 webhook 设置出现某些事件(如可能影响集成的投递问题)时,我们会向该地址发送通知。
启用邮件提醒可以及早发现 webhook 投递问题,保持集成稳定。发送失败或端点无响应时,您会收到通知。
部署到云平台
准备将 webhook 处理程序部署到生产环境了吗?我们提供面向各大云提供商的专属指南,帮助您根据每个平台的最佳实践部署 webhook。
每个平台指南都包含特定提供商的环境设置、签名验证和部署步骤。