跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.waffo.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
什么是 Webhook？

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

​
第一步：在 Dashboard 中添加 Webhook

1

进入设置

在 Dashboard 中，导航到 设置 → Webhooks。
Webhooks 设置页面，分为 Test Mode 和 Live Mode 两个区域
2

选择格式

选择负载（payload）发送到目标平台时的格式 —— 自有后端用 Raw JSON，使用聊天平台格式（Slack / Discord / 飞书 / Telegram）让消息原生地呈现在该工具中，或选择 OpenClaw / Hermes（自托管的 Pancake 插件）做自定义路由与下游处理。详见下方 选择负载格式。
添加 Webhook 弹窗中展开的 Format 下拉菜单：Raw / Feishu / Slack / Discord / Telegram / OpenClaw·Hermes
3

设置 Webhook URL

输入 Waffo Pancake 发送事件通知的目标 URL。
  • 测试模式 URL：你的开发/预发布服务器（如 https://staging.yoursite.com/webhooks/waffo）
  • 生产环境 URL：你的生产服务器（如 https://yoursite.com/webhooks/waffo）
你可以为测试和生产环境设置不同的 URL，这样测试事件和真实事件就不会混在一起。
如果上一步选了 Telegram，这里要填的是 Bot Token 和 Chat ID，而不是 URL。获取方法见下方 Telegram 章节。
4

选择事件

默认订阅所有事件，取消勾选你不需要的事件即可。
5

保存

点击 Save Webhook 保存。
每个环境最多可以配置 10 个 Webhook，因此你可以把同一组事件分发到多个目标（你的后端、Slack 频道、内部仪表盘等），无需自行编写转发服务。同一环境下不允许重复添加相同的 URL。
生产环境提示：生产模式的 Webhook 只在店铺通过审核后才会真正投递。审核期间请使用测试模式 Webhook 配合预发布代码进行验证。

​
选择负载格式

Waffo 可以按照目标平台期望的格式投递事件，你不需要自己写转换器。在添加 Webhook 时选择格式即可；如果之后想换格式，重新添加一个 Webhook 即可。
格式适用场景Endpoint
Raw（默认）调用自己的后端，期望拿到带签名的标准 JSON 负载。任意 HTTPS URL
飞书 / Lark通过自定义机器人把事件推送到飞书群。https://open.feishu.cn/open-apis/bot/v2/hook/<hook-id>
Slack通过 Incoming Webhook 把事件推送到 Slack 频道。https://hooks.slack.com/services/T.../B.../<token>
Discord通过频道 Webhook 把事件推送到 Discord 频道。https://discord.com/api/webhooks/<id>/<token>
Telegram通过机器人把事件推送到 Telegram 聊天或群组。Bot Token + Chat ID（URL 由 Waffo 自动拼接）
OpenClaw / Hermes通过自托管的 Pancake 插件 路由事件，做自定义下游处理。https://relay.waffo.ai/webhook/<webhook-id>
只有 Raw 格式带 RSA-SHA256 签名。聊天平台格式通过 URL 中嵌入的 token 认证（由对应平台签发），因此不使用签名校验。

​
Raw

  1. 在你的后端暴露一个接受 POST application/json 的 HTTPS 端点。
  2. 把 URL 粘贴到 Endpoint URL 字段。
  3. 保存后打开 Webhook 详情页，复制 Signing Public Key（签名公钥），用它来验签（见 API Reference — Webhooks）。

​
飞书 / Lark

  1. 在飞书群里添加一个 自定义机器人，复制它的 Webhook URL。
  2. URL 形如 https://open.feishu.cn/open-apis/bot/v2/hook/<hook-id>（海外区域是 open.larksuite.com/...，两者都能用）。
  3. 把 URL 粘贴到 Endpoint URL 字段。

​
Slack

  1. 在 Slack 工作区里为目标频道安装一个 Incoming Webhook。
  2. 复制 Webhook URL，形如 https://hooks.slack.com/services/T.../B.../<token>。
  3. 把 URL 粘贴到 Endpoint URL 字段。

​
Discord

  1. 在目标频道里打开 编辑频道 → 整合 → Webhook → 新建 Webhook，复制 URL。
  2. 格式：https://discord.com/api/webhooks/<id>/<token>。
  3. 把 URL 粘贴到 Endpoint URL 字段。

​
Telegram

Telegram 需要 Bot Token 和 Chat ID 两个值 —— Waffo 会自动为你拼出 Telegram 的 sendMessage URL。
  1. 与 @BotFather 对话，创建（或选用）一个机器人，复制它的 token，形如 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11。
  2. 把机器人加进目标聊天或频道，并授予它发送消息的权限。
  3. 获取 Chat ID。最简单的办法：在该聊天里发一条消息，然后访问 https://api.telegram.org/bot<TOKEN>/getUpdates，从响应里复制 chat.id。
  4. 在 添加 Webhook 的弹窗里选择 Telegram，填入 Bot Token 和 Chat ID 后保存。
底层 Waffo 会向 https://api.telegram.org/bot<TOKEN>/sendMessage 发起请求，并把 chat_id 设为你提供的值。

​
OpenClaw / Hermes（Pancake 插件）

Pancake 插件是 Waffo 的自托管中继：从 Waffo 接收事件，运行你的自定义逻辑（模板渲染、限流、多目标分发），再转发到任意位置。OpenClaw 和 Hermes 是该插件的两种开箱即用形态，选你的技术栈匹配的那个即可。
  1. 用对应的命令安装插件： 
    # OpenClaw
npx -p @waffo/pancake-plugin openclaw-setup

# Hermes
npx -p @waffo/pancake-plugin hermes-setup
    完整安装指南：github.com/waffo-com/waffo-pancake-plugin。
  2. 安装后插件会给你一个形如 https://relay.waffo.ai/webhook/<webhook-id> 的中继 URL。
  3. 在 添加 Webhook 弹窗里选择 OpenClaw / Hermes，粘贴中继 URL 并保存。

​
第二步：了解事件类型

Waffo Pancake 会发送以下 Webhook 事件：

​
订单事件

事件触发时机常见操作
order.completed订单完成交付商品、授予访问权限

​
订阅事件

事件触发时机常见操作
subscription.activated订阅已激活创建账户、设置限额
subscription.payment_succeeded订阅扣款成功延长访问期限
subscription.updated订阅详情变更更新访问级别
subscription.canceling已请求取消通知团队、发送挽留优惠
subscription.uncanceled订阅已重新激活恢复完整访问
subscription.canceled订阅完全终止撤销访问
subscription.past_due付款失败通知客户、重试

​
退款事件

事件触发时机常见操作
refund.succeeded退款处理成功撤销访问、更新记录
refund.failed退款处理失败通知商户、调查原因

​
第三步：配置邮件通知

除了 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 进行本地开发

在本地开发 webhook 处理器时，Pancake 服务器无法直接访问 http://localhost:3000。你需要一个公网 HTTPS 隧道把外部请求转发到本地端口。我们推荐 ngrok —— 开发用免费，且会保留所有自定义请求头（包括 X-Waffo-Signature）。

​
为什么必须用隧道

Webhook 投递是入站到你的服务器：Pancake 主动 POST 到你配置的 URL。localhost 地址只能在你本机访问，没有隧道这些请求根本到达不了。隧道为你的本地服务在开发期间提供一个公网可达的 HTTPS 主机名。

​
安装并启动 ngrok

1

安装

2

登录授权（免费层即可）

在 ngrok.com 注册账号，从 dashboard 复制 authtoken，然后运行：
ngrok config add-authtoken <your-authtoken>
3

启动隧道

把 ngrok 指向本地服务的端口。如果你的 webhook handler 跑在 localhost:3000：
ngrok http 3000
ngrok 会输出类似：
Forwarding  https://abc-123-456-789.ngrok-free.app -> http://localhost:3000
复制 https://...ngrok-free.app 这个 URL —— 这就是你的公网 webhook 端点。

​
接入 Pancake

1

配置 Test Webhook URL

在商户控制台进入对应店铺，前往 Settings → Webhooks。把 ngrok URL（追加你的 handler 路径，如 https://abc-123.ngrok-free.app/api/webhooks/waffo）填入 Test Webhook URL，勾选要接收的事件，保存。
只在 Test 环境用 ngrok URL。绝对不要把临时隧道 URL 放进 Production webhook —— 生产流量必须打到一个稳定的、已部署的端点。
2

触发事件

可以在控制台点 Send test event，或者在 test mode 下做一笔真实操作（例如创建结账并用测试卡完成支付）。
3

检查请求

打开 ngrok 自带的本地 web inspector：http://127.0.0.1:4040 —— 它会展示每一条经过的请求,包括 headers 和 body。确认 X-Waffo-Signature 这个 header 存在。
4

在 handler 中验签

查看本地服务日志,应该能看到 webhook POST 进来,verifyWebhook() 验签通过。如果验签失败,看下面的常见踩坑。

​
常见踩坑

现象原因解决方案
localtunnel 始终验签 401localtunnel 会剥离自定义 HTTP 请求头,导致 X-Waffo-Signature 永远到达不了 handler改用 ngrok 或 cloudflared —— 两者都保留所有 header
重启 ngrok 后 URL 变了免费层每次 ngrok http 都会分配一个新的随机子域名每次重启都要回控制台更新 Test Webhook URL。频繁联调可考虑 ngrok 付费层的固定子域名
隔一段时间事件不来了免费 ngrok 会话有几小时上限会自动断开重启 ngrok http 3000 并重新粘贴新 URL
同一事件 Pancake 重发了多次你的 handler 返回了非 2xx,Pancake 按指数退避策略重试修复 handler,然后等下次重试,或在控制台 webhook delivery log 中点 Resend

​
替代方案：Cloudflared

如果你偏好不需要注册账号的方案,cloudflared 用法类似： 
cloudflared tunnel --url http://localhost:3000
它同样保留 header,临时隧道无需注册,会输出 *.trycloudflare.com 形式的 URL 直接粘到控制台即可。代价是没有内置请求 inspector UI —— 你只能靠自己的服务日志排查。

​
联调自检清单

  • 本地服务已启动并监听预期端口
  • ngrok http <port> 在跑,forwarding URL 已记下
  • 控制台的 Test Webhook URL 是当前的 ngrok URL（含 handler 路径）
  • 在 http://127.0.0.1:4040 看到入站请求,带 X-Waffo-Signature header
  • 本地日志显示 verifyWebhook 验签成功并触发了事件 handler

​
最佳实践

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

​
检查清单

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

​
下一步

管理退款

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

API 参考 — Webhooks

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