配置 Webhook 通知

什么是 Webhook？

Webhook 是 Waffo Pancake 在事件发生时自动发送到你服务器的通知 — 支付成功、订阅续费、退款处理等。 为什么需要 Webhook：

自动化交付：支付后立即发送下载链接或授予访问权限
保持系统同步：订阅状态变化时更新你的数据库
实时响应：处理失败支付、取消和退款等事件

第一步：在 Dashboard 中添加 Webhook

进入设置

在 Dashboard 中，导航到 设置 → Webhooks。

Webhooks 设置页面，分为 Test Mode 和 Live Mode 两个区域

选择格式

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

添加 Webhook 弹窗中展开的 Format 下拉菜单：Raw / Feishu / Slack / Discord / Telegram / OpenClaw·Hermes

设置 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 章节。

选择事件

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

保存

点击 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

在你的后端暴露一个接受 POST application/json 的 HTTPS 端点。
把 URL 粘贴到 Endpoint URL 字段。
在 设置 → Webhooks 页面直接复制 Webhook Public Key（验签公钥）—— 选择你正在对接的环境（Test 或 Production），用它来验签（见 API Reference — Webhooks）。该公钥为平台级，所有门店共用，与你刚添加的 Webhook 无关；新增、修改、删除 Webhook URL 都不会改变它。

飞书 / Lark

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

Slack

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

Discord

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

Telegram 需要 Bot Token 和 Chat ID 两个值 —— Waffo 会自动为你拼出 Telegram 的 sendMessage URL。

与 @BotFather 对话，创建（或选用）一个机器人，复制它的 token，形如 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11。
把机器人加进目标聊天或频道，并授予它发送消息的权限。
获取 Chat ID。最简单的办法：在该聊天里发一条消息，然后访问 https://api.telegram.org/bot<TOKEN>/getUpdates，从响应里复制 chat.id。
在 添加 Webhook 的弹窗里选择 Telegram，填入 Bot Token 和 Chat ID 后保存。

底层 Waffo 会向 https://api.telegram.org/bot<TOKEN>/sendMessage 发起请求，并把 chat_id 设为你提供的值。

OpenClaw / Hermes（Pancake 插件）

Pancake 插件是 Waffo 的自托管中继：从 Waffo 接收事件，运行你的自定义逻辑（模板渲染、限流、多目标分发），再转发到任意位置。OpenClaw 和 Hermes 是该插件的两种开箱即用形态，选你的技术栈匹配的那个即可。

用对应的命令安装插件：

# OpenClaw
npx -p @waffo/pancake-plugin openclaw-setup

# Hermes
npx -p @waffo/pancake-plugin hermes-setup

完整安装指南：github.com/waffo-com/waffo-pancake-plugin。

安装后插件会给你一个形如 https://relay.waffo.ai/webhook/<webhook-id> 的中继 URL。
在 添加 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

设置测试 Webhook URL

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

创建测试购买

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

验证接收

检查你的服务器日志，确认 Webhook 已被正确接收和处理。

使用 ngrok 进行本地开发

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

为什么必须用隧道

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

安装并启动 ngrok

安装

macOS：brew install ngrok
Windows / Linux：从 ngrok.com/download 下载

登录授权（免费层即可）

在 ngrok.com 注册账号，从 dashboard 复制 authtoken，然后运行：

ngrok config add-authtoken <your-authtoken>

启动隧道

把 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

配置 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 —— 生产流量必须打到一个稳定的、已部署的端点。

触发事件

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

检查请求

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

在 handler 中验签

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

常见踩坑

现象	原因	解决方案
localtunnel 始终验签 401	localtunnel 会剥离自定义 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

最佳实践

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

检查清单

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

AI 集成

商业模式

运维集成

什么是 Webhook？

第一步：在 Dashboard 中添加 Webhook

选择负载格式

Raw

飞书 / Lark

Slack

Discord

Telegram

OpenClaw / Hermes（Pancake 插件）

第二步：了解事件类型

订单事件

订阅事件

退款事件

第三步：配置邮件通知

商户通知

客户通知

Webhook 工作原理

重试策略

开发者：代码集成

1. 创建 Webhook 端点

2. 验证签名

3. 处理事件

4. 快速响应

测试 Webhook

使用 ngrok 进行本地开发

为什么必须用隧道

安装并启动 ngrok

接入 Pancake

常见踩坑

替代方案：Cloudflared

联调自检清单

最佳实践

检查清单

下一步

管理退款

API 参考 — Webhooks

​什么是 Webhook？

​第一步：在 Dashboard 中添加 Webhook

​选择负载格式

​Raw

​飞书 / Lark

​Slack

​Discord

​Telegram

​OpenClaw / Hermes（Pancake 插件）

​第二步：了解事件类型

​订单事件

​订阅事件

​退款事件

​第三步：配置邮件通知

​商户通知

​客户通知

​Webhook 工作原理

​重试策略

​开发者：代码集成

​1. 创建 Webhook 端点

​2. 验证签名

​3. 处理事件

​4. 快速响应

​测试 Webhook

​使用 ngrok 进行本地开发

​为什么必须用隧道

​安装并启动 ngrok

​接入 Pancake

​常见踩坑

​替代方案：Cloudflared

​联调自检清单

​最佳实践

​检查清单

​下一步

管理退款

API 参考 — Webhooks

什么是 Webhook？

第一步：在 Dashboard 中添加 Webhook

选择负载格式

Raw

飞书 / Lark

Slack

Discord

Telegram

OpenClaw / Hermes（Pancake 插件）

第二步：了解事件类型

订单事件

订阅事件

退款事件

第三步：配置邮件通知

商户通知

客户通知

Webhook 工作原理

重试策略

开发者：代码集成

1. 创建 Webhook 端点

2. 验证签名

3. 处理事件

4. 快速响应

测试 Webhook

使用 ngrok 进行本地开发

为什么必须用隧道

安装并启动 ngrok

接入 Pancake

常见踩坑

替代方案：Cloudflared

联调自检清单

最佳实践

检查清单

下一步