跳转到主要内容

​
什么是 Webhook？

Webhook 是 Waffo Pancake 在事件发生时自动发送到你服务器的通知 — 支付成功、订阅续费、退款处理等。 为什么需要 Webhook：
  • 自动化交付：支付后立即发送下载链接或授予访问权限
  • 保持系统同步：订阅状态变化时更新你的数据库
  • 实时响应：处理失败支付、取消和退款等事件

​
第一步：在 Dashboard 中配置 Webhook URL

1

进入设置

在 Dashboard 中，导航到 设置 → Webhooks。
Webhook 设置页面
2

设置 Webhook URL

输入 Waffo Pancake 发送事件通知的目标 URL。
  • 测试模式 URL：你的开发/预发布服务器（如 https://staging.yoursite.com/webhooks/waffo）
  • 生产环境 URL：你的生产服务器（如 https://yoursite.com/webhooks/waffo）
你可以为测试和生产环境设置不同的 URL，这样测试事件和真实事件就不会混在一起。
3

保存

点击 保存 激活 Webhook 通知。

​
第二步：了解事件类型

Waffo Pancake 会发送以下 Webhook 事件：

​
支付事件

事件触发时机常见操作
payment.succeeded支付成功完成交付商品、授予访问权限
payment.failed支付尝试失败通知客户、重试
payment.refunded退款已处理撤销访问、更新记录

​
订阅事件

事件触发时机常见操作
subscription.created新订阅创建创建账户、设置限额
subscription.updated方案变更或续费更新访问级别
subscription.canceled订阅完全终止撤销访问
subscription.expired订阅过期清理资源

​
第三步：配置邮件通知

除了 Webhook 事件，你还可以为自己和客户配置邮件通知。

​
商户通知

进入 设置 → 通知 选择哪些事件触发给你的邮件提醒：
  • 新订单
  • 新订阅
  • 支付失败
  • 退款请求
通知设置

​
客户通知

客户会自动收到以下事件的邮件：
  • 订单确认
  • 订阅确认
  • 订阅续费
  • 订阅取消
  • 支付失败
你可以在通知设置中开关这些选项。

​
Webhook 工作原理

事件发生（如支付成功）
    ↓
Waffo Pancake 向你的 Webhook URL 发送 POST 请求
    ↓
你的服务器接收事件
    ↓
你的服务器处理事件（交付商品、更新数据库等）
    ↓
你的服务器返回 200 OK

​
重试策略

如果你的服务器没有返回 2xx 状态码，Waffo Pancake 会重试：
重试次数延迟
第 1 次重试5 分钟
第 2 次重试30 分钟
第 3 次重试2 小时
第 4 次重试8 小时
第 5 次重试24 小时
5 次重试都失败后，该事件将被标记为失败。

​
开发者：代码集成

如果你要将 Webhook 与服务器集成，流程如下：

​
1. 创建 Webhook 端点

你的服务器需要一个 POST 端点来接收事件。具体实现取决于你的技术栈。

​
2. 验证签名

每个 Webhook 请求都包含签名头用于安全验证。验证签名以确保请求来自 Waffo Pancake 而非恶意第三方。

​
3. 处理事件

解析事件类型和数据，然后执行相应操作（交付商品、更新订阅状态等）。

​
4. 快速响应

尽快返回 200 状态码。如果需要执行重量级处理，在响应之后异步执行。
详细的代码示例和签名验证说明，请参考 API 参考 — Webhooks。

​
测试 Webhook

1

设置测试 Webhook URL

在 Dashboard → 设置 → Webhooks 中，输入你的测试服务器 URL。
2

创建测试购买

使用测试模式进行一笔购买。这会向你的测试 URL 触发 Webhook 事件。
3

验证接收

检查你的服务器日志，确认 Webhook 已被正确接收和处理。
本地开发时，可以使用 ngrok 等工具将本地服务器暴露到公网，以便 Waffo Pancake 能够访问。

​
最佳实践

  1. 快速响应：立即返回 200，异步处理业务逻辑
  2. 处理重复：事件可能被发送多次 — 确保你的处理是幂等的
  3. 验证签名：处理前始终验证 Webhook 签名
  4. 记录日志：保留收到的 Webhook 日志用于调试
  5. 监控失败：在 Dashboard 中检查失败的 Webhook 投递

​
检查清单

  • 测试和生产环境的 Webhook URL 已配置
  • 团队的邮件通知已配置
  • 客户通知偏好已设置
  • 测试 Webhook 已成功接收和处理
  • 签名验证已实现（如使用代码集成）

​
下一步

管理退款

处理退款请求并跟踪退款状态

API 参考 — Webhooks

详细的 Webhook 负载格式和代码示例