Skip to main content

​
概览

Webhooks 将事件实时推送到您的服务器，无需轮询。 
Waffo Pancake 中发生事件 --> HTTP POST 到您的端点 --> 您处理事件

​
设置

1

创建 HTTPS 端点

构建一个可公开访问的端点，接受 POST 请求并返回 200 OK。
2

在控制台中注册

前往控制台 > 开发者 > Webhooks。添加您的端点 URL。
3

选择事件

选择需要接收的事件类型。
4

保存

保存您的 Webhook 配置。

​
事件类型

事件涵盖支付、订阅和退款生命周期通知。在控制台中配置 Webhooks 时，您可以选择要订阅的事件类别。
具体的事件名称和可用类别会在您配置 Webhook 端点时显示在控制台中。请参阅您的控制台以获取最新列表。

​
载荷格式

每次 Webhook 投递都是一个 HTTP POST 请求，JSON 请求体包含事件类型和关联数据： 
{
  "event": "<event_type>",
  "data": {
    // 事件相关字段
  }
}
所有 ID 为 UUID v4 格式。金额以最小货币单位表示（例如，2900 = $29.00）。时间戳为 ISO 8601 UTC 格式。

​
处理 Webhooks

快速返回 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;
  }
});

​
幂等性

事件可能会被重复投递。使用事件数据进行去重： 
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 存储到数据库中，而非内存中，以确保服务器重启后数据不丢失。

​
重试策略

投递失败后会自动重试。请确保您的端点及时返回 200 状态码以确认收到。

​
测试

使用沙盒环境测试 Webhooks：
  1. 在控制台中切换到测试模式
  2. 前往开发者 > Webhooks
  3. 执行会触发事件的操作
  4. 检查您的端点是否收到了事件
Webhooks 在测试模式和正式模式中都会触发。请确保您的端点能够区分不同环境。

​
最佳实践

  1. 使用 HTTPS — 生产环境的 Webhook 端点必须使用 HTTPS
  2. 快速响应 — 在 30 秒内返回 200
  3. 处理重复投递 — 使用 ID 进行去重
  4. 异步处理 — 不要让耗时操作阻塞响应
  5. 记录所有日志 — 记录收到的 Webhook 以便调试