跳转到主要内容

​
使用 SDK 内置的 WebhookHandler

我们强烈建议使用 SDK 方法 webhook().handleWebhook()，它会自动处理：
  • 签名校验
  • JSON 解析与事件路由
  • 响应体构建与签名
const handler = waffo.webhook()
  .onPayment((n) => handlePayment(n))
  .onRefund((n) => handleRefund(n))
  .onSubscriptionStatus((n) => handleSubscription(n))
  .onSubscriptionChange((n) => handleChange(n));

app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  const result = await handler.handleWebhook(req.body.toString(), req.headers['x-signature'] as string);
  res.setHeader('X-SIGNATURE', result.responseSignature);
  res.status(200).send(result.responseBody);
});

​
幂等处理

Waffo 可能会多次投递同一个事件。请确保你的处理逻辑具备幂等性： 
waffo.webhook().onPayment(async (notification) => {
  const orderId = notification.acquiringOrderId;

  const order = await db.order.findByAcquiringOrderId(orderId);
  if (order.status === 'PAY_SUCCESS') {
    return;
  }

  await updateOrderStatus(orderId, notification.orderStatus);
});

​
快速响应

  • SDK 会在 handler 执行完成后自动构建响应
  • 耗时操作（例如发送邮件或更新外部系统）应异步处理
  • 如果在 handler 中抛出异常，SDK 会自动返回失败响应

​
安全

  • 始终校验 X-SIGNATURE（由 SDK 自动处理）
  • 使用 HTTPS 端点
  • 在处理事件前先校验签名——在校验通过之前不要执行任何业务逻辑
  • 响应必须包含 X-SIGNATURE header（由 SDK 自动处理）