Webhooks 实时推送事件到您的服务器。无需轮询。
您的应用 <-- Webhook <-- Waffo Pancake
创建端点
构建一个接受 POST 请求的 HTTPS 端点。
事件类型
| 事件 | 说明 |
|---|
payment.completed | 支付成功 |
payment.failed | 支付失败 |
subscription.created | 新订阅开始 |
subscription.canceled | 订阅已取消 |
subscription.trial_ending | 试用期 3 天后到期 |
subscription.payment_failed | 订阅扣费失败 |
refund.created | 退款工单已创建 |
refund.approved | 退款已批准 |
负载格式
Webhook 负载遵循标准的 Waffo Pancake API 响应格式：
{
"event": "payment.completed",
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"orderId": "660e8400-e29b-41d4-a716-446655440001",
"amount": 2900,
"currency": "USD",
"status": "completed",
"createdAt": "2026-01-15T10:30:00.000Z"
}
}
所有 ID 使用 UUID v4 格式。金额以最小货币单位表示（如 2900 = $29.00）。时间戳使用 ISO 8601 UTC 格式。
订阅事件示例
{
"event": "subscription.created",
"data": {
"id": "770e8400-e29b-41d4-a716-446655440002",
"status": "active",
"billingPeriod": "monthly",
"amount": 2900,
"currency": "USD",
"currentPeriodEnd": "2026-02-15T10:30:00.000Z"
}
}
正确响应
快速返回 200 OK。如需要，异步处理重型工作。
app.post('/webhooks/waffo', (req, res) => {
// 立即响应
res.status(200).send('OK');
// 异步处理
const { event, data } = req.body;
switch (event) {
case 'payment.completed':
handlePaymentCompleted(data);
break;
case 'subscription.created':
handleSubscriptionCreated(data);
break;
case 'subscription.canceled':
handleSubscriptionCanceled(data);
break;
}
});
重试策略
失败的推送会自动重试：
| 尝试次数 | 延迟 |
|---|
| 1 | 立即 |
| 2 | 5 分钟 |
| 3 | 30 分钟 |
| 4 | 2 小时 |
| 5 | 24 小时 |
幂等性
事件可能会被多次推送。使用事件数据（如订单或支付 ID）进行去重，确保您的处理器只处理每个事件一次。
const processedEvents = new Set();
app.post('/webhooks/waffo', (req, res) => {
const { event, data } = req.body;
const eventKey = `${event}:${data.id}`;
if (processedEvents.has(eventKey)) {
return res.status(200).send('Already processed');
}
processedEvents.add(eventKey);
res.status(200).send('OK');
// 处理事件
processWebhook(event, data);
});
在生产环境中，将已处理的事件 ID 存储在数据库中，而非内存中，以便在服务器重启后保持持久化。
最佳实践
- 使用 HTTPS — 生产环境 webhook 端点的必要条件
- 快速响应 — 30 秒内返回 200；异步处理重型工作
- 处理重复 — 事件可能重试；使用 ID 进行去重
- 异步处理 — 不要用重型处理阻塞响应
- 记录日志 — 记录所有收到的 webhook 用于调试
使用测试模式向您的 webhook 端点发送测试事件：
- 在控制台顶部切换到测试模式
- 前往 开发者 —> Webhooks
- 在测试模式下执行操作（创建订单、完成支付）
- 检查您的端点是否收到 webhook 事件
Webhook 在测试和正式模式下都会触发。确保您的端点能够通过原始操作的 X-Environment 上下文区分测试和正式事件。
在控制台中查看 webhook 推送日志：
- 推送状态（成功/失败）
- 您端点返回的 HTTP 响应码
- 发送的负载
- 时间戳和重试次数
下一步
Webhook 指南
分步 webhook 集成教程。
