Skip to main content

概览

Webhooks 将事件实时推送到您的服务器,无需轮询。

设置

1

创建 HTTPS 端点

构建一个可公开访问的端点,接受 POST 请求并返回 200 OK。
2

在控制台中注册

前往控制台 > API 与开发 > Webhooks。添加您的端点 URL。
3

选择事件

选择需要接收的事件类型。
4

保存

保存您的 Webhook 配置。

事件类型

事件涵盖支付、订阅和退款生命周期通知。在控制台中配置 Webhooks 时,您可以选择要订阅的事件类别。
具体的事件名称和可用类别会在您配置 Webhook 端点时显示在控制台中。请参阅您的控制台以获取最新列表。

载荷格式

每次 Webhook 投递都是一个 HTTP POST 请求,JSON 请求体包含事件类型和关联数据:
所有 ID 为 UUID v4 格式。金额以显示格式字符串表示(例如,“29.00” = $29.00)。时间戳为 ISO 8601 UTC 格式。

处理 Webhooks

快速返回 200 OK。如果处理逻辑较重,请异步处理。

幂等性

事件可能会被重复投递。使用事件数据进行去重:
在生产环境中,请将已处理的事件 ID 存储到数据库中,而非内存中,以确保服务器重启后数据不丢失。

重试策略

投递失败后会自动重试。请确保您的端点及时返回 200 状态码以确认收到。

测试

使用测试模式测试 Webhooks:
  1. 在控制台中切换到测试模式
  2. 前往开发者 > Webhooks
  3. 执行会触发事件的操作
  4. 检查您的端点是否收到了事件
Webhooks 在测试模式和正式模式中都会触发。请确保您的端点能够区分不同环境。

最佳实践

  1. 使用 HTTPS — 生产环境的 Webhook 端点必须使用 HTTPS
  2. 快速响应 — 在 30 秒内返回 200
  3. 处理重复投递 — 使用 ID 进行去重
  4. 异步处理 — 不要让耗时操作阻塞响应
  5. 记录所有日志 — 记录收到的 Webhook 以便调试