概览
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。如果处理逻辑较重,请异步处理。
幂等性
事件可能会被重复投递。使用事件数据进行去重:重试策略
投递失败后会自动重试。请确保您的端点及时返回200 状态码以确认收到。
测试
使用测试模式测试 Webhooks:- 在控制台中切换到测试模式
- 前往开发者 > Webhooks
- 执行会触发事件的操作
- 检查您的端点是否收到了事件
Webhooks 在测试模式和正式模式中都会触发。请确保您的端点能够区分不同环境。
最佳实践
- 使用 HTTPS — 生产环境的 Webhook 端点必须使用 HTTPS
- 快速响应 — 在 30 秒内返回 200
- 处理重复投递 — 使用 ID 进行去重
- 异步处理 — 不要让耗时操作阻塞响应
- 记录所有日志 — 记录收到的 Webhook 以便调试