跳转到主要内容
Webhook 封面图
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 仪表板并前往 Settings > Webhooks
2

Create Webhook Endpoint

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

Add Endpoint URL

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

Select Events to Receive

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

Get Secret Key

在设置页面获取您的 webhook Secret Key。您将用它来验证接收到的 webhook 的真实性。
妥善保管您的 webhook 密钥,切勿在客户端代码或公开仓库中泄露。
6

Rotate Secret (Optional)

如有必要,可轮换 webhook 密钥以提升安全性。在 webhook 设置中点击 Rotate Secret 按钮。
轮换密钥会使其失效替换为新密钥。旧密钥在接下来的 24 小时内仍然有效。之后使用旧密钥验证将失败。
定期或在怀疑当前密钥泄露时立即进行轮换。

配置订阅事件

您可以为每个 webhook 端点配置希望接收的特定事件。

访问事件配置

1

Navigate to Webhook Details

进入 Dodo Payments 仪表板并前往 Settings > Webhooks
2

Select Your Endpoint

点击要配置的 webhook 端点。
3

Open Event Settings

在 webhook 详情页面,您会看到“Subscribed events”部分。点击 Edit 按钮修改事件订阅。

管理事件订阅

1

View Available Events

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

Search and Filter

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

Select Events

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

Review Event Details

将鼠标悬停在每个事件旁的提示图标(ⓘ)上,即可查看该事件触发的描述。
5

Save Configuration

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

Webhook 交付

超时

Webhook 的 15 秒超时窗口 适用于连接和读取操作。确保您的端点快速响应以避免超时。
通过立即返回 200 状态码确认接受 webhook,然后在后台异步处理实际逻辑。

自动重试

如果 webhook 交付失败,Dodo Payments 会自动以指数退避的方式重试,以防止对您的系统造成过大压力。
尝试延迟描述
1立即第一次重试立即发生
25 秒第二次尝试在短暂延迟后进行
35 分钟第三次尝试增加退避
430 分钟第四次尝试继续退避
52 小时第五次尝试延长延迟
65 小时第六次尝试更长延迟
710 小时第七次尝试最大延迟
810 小时最后一次尝试 - 如果不成功,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 规范自行验证签名:
  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 会被重试。

最佳实践

始终为 webhook 端点使用 HTTPS URL。HTTP 端点容易受到中间人攻击,并会暴露您的 webhook 数据。
收到 webhook 后立即返回 200 状态码。异步处理事件以避免超时。
app.post('/webhook', async (req, res) => {
  // Acknowledge receipt immediately
  res.status(200).json({ received: true });
  
  // Process asynchronously
  processWebhookAsync(req.body).catch(console.error);
});
使用 webhook-id 标头实现幂等性,以安全地多次处理相同事件而不会带来副作用。
使用环境变量或密钥管理器安全存储 webhook 密钥。切勿将密钥提交到版本控制。

Webhook 有效负载结构

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

请求格式

POST /your-webhook-url
Content-Type: application/json

头部

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

请求体

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

示例有效负载

{
  "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 集成,以确保您的端点正常工作,然后再上线。
端点详情

访问测试界面

1

Navigate to Webhooks

进入 Dodo Payments 仪表板并前往 Settings > Webhooks
2

Select Your Endpoint

点击您的 webhook 端点,进入其详情页面。
3

Open Testing Tab

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

测试您的 Webhook

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

Select Event Type

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

Review Schema and Example

界面同时显示所选事件类型的 Schema(数据结构)和 Example(示例有效负载)。
3

Send Test Event

点击 Send Example 按钮向您的端点发送测试 webhook。
注意:通过测试界面发送的失败消息不会被重试,仅用于测试用途。

验证您的测试

1

Check Your Endpoint

监控 webhook 端点日志以确认测试事件是否已接收。
2

Verify Signature

使用测试有效负载验证您的签名验证是否正常工作。
3

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 事件转发到本地开发服务器:
dodo wh listen
CLI 会打开与 Dodo Payments 的 WebSocket 连接,并将每个 webhook 事件转发到本地端点(例如 http://localhost:3000/webhook),保留所有标头,包括用于验证的签名标头。
监听器仅适用于测试模式 API 密钥。运行 dodo login 并选择测试模式后再使用该命令。

触发模拟 Webhook 事件

向任意端点发送模拟 webhook 有效负载,而无需创建真实交易:
dodo wh trigger
此交互式工具让您从 22 种受支持的事件类型中进行选择,并将真实感的模拟有效负载发送至您的端点。它会循环运行,因此您可以在一个会话中测试多个事件。
来自 dodo wh trigger 的模拟 webhook 有效负载不带签名。测试期间请使用 unsafe_unwrap() 替代 unwrap()

CLI Webhook Testing Docs

查看完整的 CLI webhook 测试文档

高级设置

高级设置选项卡提供更多配置选项,便于微调 webhook 端点行为。

速率限制(节流)

控制 webhook 事件发送到端点的频率,防止系统过载。
1

Access Rate Limit Settings

Advanced 选项卡中找到“Rate Limit (throttling)”部分。
2

Configure Rate Limit

点击 Edit 按钮以修改速率限制设置。
默认情况下,webhook 设置为“不限速”,即事件发生时立即投递。
3

Set Limits

配置所需的速率限制,以控制 webhook 投递频率并防止系统过载。
当 webhook 处理程序需要时间处理事件或想要将多个事件批量处理时,请使用速率限制。

自定义标头

为发送到端点的所有 webhook 请求添加自定义 HTTP 标头。这对于身份验证、路由或添加元数据非常有用。
1

Add Custom Header

在“Custom Headers”部分输入自定义标头的和值。
2

Add Multiple Headers

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

Save Configuration

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

转换

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

Enable Transformations

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

Configure Transformation

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

Test Transformation

使用测试界面验证转换在上线前是否正常工作。
转换可能显著影响 webhook 投递性能。请充分测试并保持转换逻辑简洁高效。
转换特别适用于:
  • 在不同数据格式之间转换
  • 根据特定条件筛选事件
  • 向有效负载添加计算字段
  • 将事件路由到不同的微服务

监控 Webhook 日志

Logs 选项卡提供全面的 webhook 投递状态可见性,帮助您有效监控、调试和管理 webhook 事件。
日志

活动监控

Activity 选项卡通过可视化分析提供 webhook 投递性能的实时洞察。
活动

邮件提醒

通过自动邮件通知随时了解 webhook 健康状况。当 webhook 投递开始失败或端点停止响应时,您会收到邮件提醒,便于快速排查问题并保持集成稳定运行。
Webhook 警报设置,显示邮件通知配置

启用邮件提醒

1

Navigate to Alerting Settings

进入 Dodo Payments 仪表板,导航至 Dashboard → Webhooks → Alerting
2

Enable Email Notifications

打开 Email notifications 开关以开始接收 webhook 投递问题提醒。
3

Configure Email Address

输入希望接收 webhook 警报的邮箱地址。当 webhook 设置出现某些事件(如可能影响集成的投递问题)时,我们会向该地址发送通知。
启用邮件提醒可以及早发现 webhook 投递问题,保持集成稳定。发送失败或端点无响应时,您会收到通知。

部署到云平台

准备将 webhook 处理程序部署到生产环境了吗?我们提供面向各大云提供商的专属指南,帮助您根据每个平台的最佳实践部署 webhook。
每个平台指南都包含特定提供商的环境设置、签名验证和部署步骤。