Skip to main content
Webhook Cover Image
Webhooks 在 Dodo Payments 账户中发生特定事件时提供实时通知。使用 webhooks 来自动化工作流程、更新数据库、发送通知,并保持系统同步。
我们的 webhook 实现遵循 Standard Webhooks 规范,确保与行业最佳实践和现有 webhook 库兼容。

主要功能

Real-time Delivery

当事件发生时接收即时通知

Secure by Default

包括 HMAC SHA256 签名验证

Automatic Retries

内置重试逻辑,具有指数退避

Event Filtering

仅订阅您需要的事件

入门

Dodo Payments webhooks 门户已重建为原生 dashboard 体验。您现有的 endpoints、signing secrets、signature verification、event names 和 webhook payloads 均未改变。无需进行任何集成工作。
功能位置。
  • 位于 Developer → Webhooks 下EndpointsEvent catalogLogsActivitySettings 标签页。
  • 位于单个 endpoint 中Overview 标签页,其中包含 delivery stats、signing secret 和 Replay history,以及 TestingAdvanced 标签页与批量 replay 操作。
  • 位于消息中 — 从 Logs 标签页打开;您可以单独 replay 每次 delivery attempt,无需打开 endpoint。
1

Access Webhook Settings

前往 Dodo Payments Dashboard,然后进入 Developer → Webhooks
2

Create Webhook Endpoint

点击 Add endpoint,打开 endpoint 创建侧边面板。
3

Enter Endpoint URL or Choose Integration

输入您希望接收 webhook events 的 URL,或选择 integration connector,将 events 路由到第三方服务(Slack、Discord、Zapier、Resend 等)。
4

Select Events to Receive

选择 endpoint 应监听的具体 events。Events 按 resource 分组,以可搜索的树形结构组织。您可以选择单个 events,也可以选择父级 resource 来接收所有相关 events。
只有选中的 events 才会触发发送到 endpoint 的 webhooks,从而帮助您避免不必要的流量和处理。
5

Create Endpoint

点击 Create endpoint 保存配置。
6

Get Secret Key

您的 webhook signing secret 会显示在 endpoint 的 Overview 标签页中。您将使用它来验证所接收 webhooks 的真实性。
请妥善保管 webhook secret key,切勿将其暴露在客户端代码或公开代码仓库中。
7

Rotate Secret (Optional)

如有需要,您可以轮换 webhook secret 以增强安全性。点击 Rotate secret,该按钮位于 Overview 标签页中 secret 旁边。
轮换 secret 会使当前 secret 失效,并将其替换为新的 secret。旧 secret 仅在接下来的 24 小时内有效。此后,使用旧 secret 进行验证将失败。
定期轮换 secret;如果您怀疑当前 secret 已泄露,请立即轮换。

Integration Connectors

您无需自行构建 webhook receiver,也可以使用 integration connectors 将 webhook events 直接路由到第三方服务。这样便无需为常见平台编写和维护自定义 webhook handlers。

Connectors 的工作方式

Connector 会执行转换,将 Dodo Payments event 转换为目标服务所需的格式。您需要提供的详细信息取决于目标服务: Dashboard 中的 connector picker 会显示当前对您的 business 可用的完整集合。因此,请将上表视为提供分步设置说明的目标服务列表,而非完整清单。有关各目标服务在接收 events 后可以执行的操作,请参阅 External Integrations

设置 Connector

创建或编辑 endpoint 时选择一个 connector,侧边面板会显示针对该目标服务编写的设置说明,例如如何在 Slack 中创建 incoming webhook URL,或在哪里查找 Resend API key。保存前,请运行 connector transformation test,以确认 event 已正确转换为目标服务所需的格式。
使用 connector 可在无需编写代码的情况下连接受支持的目标服务。如果需要自定义逻辑,请改用带有 transformation 的标准 endpoint。

配置订阅的 Events

您可以配置每个 webhook endpoint 应接收的具体 events。
1

Navigate to Webhook Endpoints

前往 Dodo Payments Dashboard,然后进入 Developer → Webhooks
2

Select Your Endpoint

点击要配置的 webhook endpoint。
3

Open Event Configuration

点击 Edit,打开 endpoint 配置侧边面板。
4

Browse Event Types

Event type selector 会显示所有可用的 webhook events,这些 events 按 resource 分组并以可搜索的树形结构组织(例如 paymentsubscriptiondispute)。使用搜索栏可按名称或关键字快速查找特定 events。
5

Select Events

勾选您希望接收的 events 旁边的复选框。您可以:
  • 选择单个 events(例如 payment.succeededpayment.failed
  • 选择父级 resource 以接收所有相关 events
  • 根据需求混合选择特定 events
6

Save Configuration

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

Event Catalog

进入 Developer → Webhooks,打开 Event catalog 标签页。该页面列出了 Dodo Payments 可以发送的所有 event types,方便您在为 endpoint 订阅 event 前了解可用内容。选择某个 event 可查看其 schema 和示例 payload,这是检查您计划读取的字段格式最快的方式。

Webhook Events Guide

浏览相同的 events 作为参考文档,并按 resource 分组。

Webhook Delivery

超时

Webhooks 对 connection 和 read operations 均设有 15 秒超时窗口。请确保 endpoint 快速响应,以避免超时。
通过立即使用 200 status code 确认收到 webhook,然后在后台异步处理实际业务。

自动重试

如果 webhook delivery 失败,Dodo Payments 会自动采用 exponential backoff 进行重试,以避免系统过载。
每个 webhook event 最多重试 8 次。例如,如果 webhook 在成功前失败三次,则从第一次尝试开始计算,总 delivery 时间约为 35 分钟 5 秒。
您可以随时使用 Dodo Payments dashboard 手动重试单条消息,或批量恢复所有失败的消息。

幂等性

每个 webhook event 都包含唯一的 webhook-id header。使用此标识符实现幂等性,防止重复处理。
请始终实现幂等性检查。由于存在重试,您可能会多次收到同一个 event。

Event Ordering

由于重试或网络状况,Webhook events 可能会乱序到达。请设计系统,使其能够按任意顺序处理 events。
无论 webhook event 最初何时发出,您收到的始终是 delivery 时最新的 payload

保护 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 验证 signatures
  • unsafe_unwrap():不验证 signatures,直接解析 payloads
初始化 Dodo Payments client 时,通过 DODO_PAYMENTS_WEBHOOK_KEY 提供 webhook secret。

手动 verification(替代方案)

如果您不使用 SDK,可以按照 Standard Webhooks spec 自行验证 signatures:
  1. webhook-idwebhook-timestamp 和精确的原始字符串化 payload 用句点(.)连接,构建 signed message。
  2. 使用 Dashboard 中的 webhook secret key,计算该字符串的 HMAC SHA256。
  3. 将计算出的 signature 与 webhook-signature header 进行比较。如果匹配,则 webhook 是有效的。
我们遵循 Standard Webhooks specification。您可以使用其 libraries 验证 signatures:https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries。有关 event payload formats,请参阅 Webhook Payload

响应 Webhooks

  • 您的 webhook handler 必须返回 2xx status code,以确认收到 event。
  • 任何其他 response 都会被视为失败,并且 webhook 将被重试。

最佳实践

始终为 webhook endpoints 使用 HTTPS URLs。HTTP endpoints 容易受到中间人攻击,并会暴露 webhook data。
收到 webhook 后立即返回 200 status code。异步处理 event,以避免超时。
使用 webhook-id header 实现幂等性,从而安全地多次处理同一个 event 且不产生副作用。
使用 environment variables 或 secrets manager 安全地存储 webhook secret。切勿将 secrets 提交到 version control。

Webhook Payload Structure

了解 webhook payload structure 有助于正确解析和处理 events。

Request Format

Headers

string
必填
此 webhook event 的唯一标识符。使用它进行幂等性检查。
string
必填
用于验证 webhook authenticity 的 HMAC SHA256 signature。
string
必填
发送 webhook 时的 Unix timestamp(以秒为单位)。

Request Body

string
必填
您的 Dodo Payments business identifier。
string
必填
触发此 webhook 的 event type(例如 payment.succeededsubscription.active)。
string
必填
Event 发生时间的 ISO 8601 格式 timestamp。
object
必填
包含 event 详细信息的 event-specific payload。

示例 Payload

Event Types

浏览所有可用的 webhook event types

Event Payloads

查看每个 event 的详细 payload schemas

Handle Payment Failures

响应 payment.failed 并恢复 declined payments

测试 Webhooks

您可以直接从 Dodo Payments dashboard 测试 webhook integration,确保 endpoint 在上线前正常工作。
1

Navigate to Webhooks

前往 Dodo Payments Dashboard,然后进入 Developer → Webhooks
2

Select Your Endpoint

点击 webhook endpoint 以访问其详情页。
3

Open Testing Tab

点击 Testing 标签页,访问 webhook testing interface。

发送示例 Event

Testing 标签页会向此 endpoint 发送示例 payload,方便您验证 receiver。
1

Select Event Type

使用 Select an event type 选择要测试的 event,例如 payment.succeededpayment.failed
2

Send Example

点击 Send example。示例 payload 会像真实 event 一样发送到 endpoint URL,并使用相同方式签名。
从 Testing 标签页发送的失败消息不会重试。请使用它验证 receiver,而不要用来测试 retry schedule。
3

Check Your Endpoint

该标签页会记录 Last example sent 的发送时间。请确认 event 已到达、signature verification 已通过,并且您返回了 2xx status code。

Implementation Example

以下是一个完整的 Express.js implementation,展示 webhook verification 和 handling:
在处理 production events 前,请使用 dashboard testing interface 对 webhook handler 进行全面测试。这有助于尽早发现并修复问题。

使用 CLI 测试 Webhooks

Dodo Payments CLI 提供两个命令,用于在 local development 期间测试 webhooks,无需离开 terminal。

在本地监听 Live Webhooks

实时将 test mode account 的真实 webhook events 转发到本地 development server:
CLI 会与 Dodo Payments 建立 WebSocket connection,并将每个 webhook event 转发到本地 endpoint(例如 http://localhost:3000/webhook),同时保留包括 signature headers 在内的所有 headers,以便进行 verification testing。
该 listener 仅适用于 test mode API keys。运行 dodo login,并在使用此命令前选择 Test Mode。

触发 Mock Webhook Events

向任意 endpoint 发送 mock webhook payloads,无需创建真实 transactions:
此 interactive tool 允许您选择 event type,并向 endpoint 发送逼真的 mock payload。它会循环运行,方便您在一次 session 中测试多个 events。 trigger command 覆盖 Dodo Payments delivery 的全部 46 种 event types,包括 subscription、payment、refund、dispute、license key、payout、credit、abandoned checkout、dunning 和 entitlement grant 系列 — exact list 请参阅 Supported Webhook Events
来自 dodo wh trigger 的 mock webhook payloads 未签名。仅在 testing 期间,在 webhook handler 中使用 unsafe_unwrap(),而不是 unwrap()

CLI Webhook Testing Docs

查看完整的 CLI webhook testing documentation

Advanced Settings

Advanced 标签页提供额外的 configuration options,用于精细调整 webhook endpoint behavior。

Rate Limiting(Throttling)

控制 webhook events 发送到 endpoint 的速率,避免系统过载。
1

Open Advanced Tab

在 endpoint details page 中,点击 Advanced 标签页。
2

Configure Rate Limit

在 “Rate Limit (throttling)” 部分,点击 Edit 修改 rate limit settings。
默认情况下,webhooks 不应用 rate limit,这意味着 events 会在发生后立即 delivery。
3

Set Your Limit

配置所需的 rate limit,以控制 webhook delivery frequency 并防止系统过载。
当 webhook handler 需要时间处理 events,或您希望将多个 events 批量处理时,可以使用 rate limiting。

自定义 Headers

向发送到 endpoint 的所有 webhook requests 添加自定义 HTTP headers。这对于 authentication、routing 或添加 metadata 很有用。
1

Add Headers

在 “Custom Headers” 部分,为每个 custom header 输入 KeyValue
2

Add Multiple Headers

根据需要点击 + 按钮添加更多 custom headers。
您的 custom headers 会包含在发送到此 endpoint 的所有 webhook requests 中。

Transformations

Transformations 允许您修改 webhook payload,并可选择将其重定向到其他 URL。此强大功能可以:
  • 在处理前修改 payload structure
  • 根据内容将 webhooks 路由到不同 endpoints
  • 从 payload 添加或移除 fields
  • 转换 data formats
1

Enable Transformations

切换 Enabled 开关以启用 transformation feature。
2

Configure Transformation

点击 Edit transformation,使用 JavaScript 定义 transformation rules。
3

Test Transformation

使用 transformation test interface 验证 transformation 在上线前是否正常工作。
Transformations 可能会影响 webhook delivery performance。请充分测试,并保持 transformation logic 简单高效。
Transformations 特别适用于:
  • 在不同 data formats 之间转换
  • 根据特定 criteria 过滤 events
  • 向 payload 添加计算字段
  • 将 events 路由到不同 microservices

监控 Webhook Logs

Logs 标签页全面展示 webhook delivery status,帮助您有效监控、调试和管理 webhook events。
1

Navigate to Logs Tab

进入 Developer → Webhooks,打开 Logs 标签页。
2

Browse Delivery History

查看所有 webhook delivery attempts 的表格,其中包含 Event type、Message ID、Event ID、Sent at、Attempted at、Response code 和 Duration 列。
3

Search and Filter

使用搜索栏按 ID 或 event type 查找特定 messages。按 status(Succeeded、Failed、Pending 等)筛选,以专注于需要调查的 events。
4

View Message Details

点击任意 message 打开 message detail page,其中显示:
  • 完整的 webhook payload
  • 每次 delivery attempt 及其 response code 和 duration
  • 每次 attempt 的 timestamp
  • endpoint 返回的任何 error messages
每次 attempt 都带有 Replay 操作,因此您可以在不离开页面的情况下重新驱动该条 message。

Activity Monitoring

进入 Developer → Webhooks,打开 Activity 标签页,查看所有 endpoints 的 delivery performance。 Delivery activity 会按时间绘制 attempts;根据时间窗口,分组方式为 Attempts per 5 minutesAttempts per hourAttempts per day。每个柱状条会按 outcome 拆分,悬停在某个分段上可查看 status、attempts 数量及其占总数的比例。在 endpoint 中,Overview 标签页的 Delivery stats (last 24h) 会汇总过去一天的相同信息。
Endpoints 标签页中的 Error rate (24h) 列可以让您快速了解哪些 endpoints 需要关注,无需先打开它们。

Replay 和恢复 Messages

重新驱动 message 的方式取决于需要处理的数量:
  • 一条 message — 从 Logs 标签页打开它,并在 attempt 上使用 Replay 操作。无需打开 endpoint。
  • 一系列 messages — 打开 endpoint,因为批量模式每次只作用于一个 endpoint。

批量 Replay

Developer → Webhooks 打开 endpoint。共有三种模式,每种模式仅作用于该 endpoint。您设置的范围取决于所选模式:
1

Open More Actions

在 endpoint 中打开 More actions,选择上述三种模式之一。
2

Set the Range

按照表格中的说明,填写该模式要求的范围。
3

Start the Run

根据所选模式,点击 RecoverReplay
每次运行都会显示在 endpoint 的 Overview 标签页中的 Replay history 下,其中包含模式、时间范围、status 以及重新发送的 messages 数量。

Email Alerts

当发送到某个 endpoint 的 webhook deliveries 失败时接收 email notification,以便在问题形成积压之前及时处理。
1

Navigate to Settings Tab

进入 Developer → Webhooks,打开 Settings 标签页。
2

Find Email Alerting

找到 Email alerting card。
3

Configure Email Addresses

输入应接收 alerts 的 addresses。多个 addresses 请用逗号分隔;留空则关闭 alerts。
4

Save

点击 Save 应用更改。
启用 email alerts,以便及早发现 webhook delivery problems,并保持可靠的 integrations。

部署到 Cloud Platforms

准备将 webhook handler 部署到 production?我们提供特定于平台的 guides,帮助您按照各平台的 best practices,将 webhooks 部署到常用 cloud providers。

Vercel

使用 serverless functions 将 webhooks 部署到 Vercel

Cloudflare Workers

在 Cloudflare 的 edge network 上运行 webhooks

Supabase Edge Functions

将 webhooks 与 Supabase 集成

Netlify Functions

将 webhooks 部署为 Netlify serverless functions
每个平台 guide 都包含特定于该 provider 的 environment setup、signature verification 和 deployment steps。

相关 API Reference

Create Webhook

以编程方式创建和配置 webhook endpoints 的 API reference

List Webhooks

获取和管理 webhook endpoints 的 API reference
最后修改于 2026年8月8日