Skip to main content

使用 SDK 内置的 WebhookHandler

我们强烈建议使用 SDK 方法 webhook().handleWebhook(),它会自动处理:
  • 签名校验
  • JSON 解析与事件路由
  • 响应体构建

幂等处理

Waffo 可能会多次投递同一个事件。请确保你的处理逻辑具备幂等性:

按最终状态处理,不依赖投递顺序

Webhook 是异步分发的通知,商户收到多个相关回调的顺序不保证。尤其是订阅首期场景中,SUBSCRIPTION_STATUS_NOTIFICATION 和 SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION 都可能发送,请不要依赖这两个回调的到达顺序。
  • 不要按回调到达顺序更新最终业务状态
  • 按事件粒度选择幂等键,例如事件 ID 或业务订单 ID;周期权益使用 subscriptionId 和周期组合去重,避免忽略后续周期
  • 如果同时订阅 SUBSCRIPTION_STATUS_NOTIFICATION 和 SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION,收到任一回调后调用 POST /api/v1/subscription/inquiry 查询最终状态,再进入统一的订阅回调处理逻辑

Subscription 权益发放

建议使用 SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION 触发周期权益发放检查。先验签,再核对对应周期的最终支付结果;收到通知本身不代表支付成功。
  • 核对 Subscription、周期和金额是否与对应套餐及当期应付金额一致
  • 确认当期支付成功且校验通过后,发放对应权益
  • 按 Subscription 和周期记录权益发放结果,重复通知不重复发放
  • 处理 PAYMENT_NOTIFICATION 时,先按 result.subscriptionInfo.subscriptionEvent 区分周期扣款、新增支付方式和补差价,不要把后两者当作新周期权益的发放依据;取值说明见 Subscription 支付事件

快速响应

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

安全

  • 始终校验 X-SIGNATURE(由 SDK 自动处理)
  • 使用 HTTPS 端点
  • 在处理事件前先校验签名——在校验通过之前不要执行任何业务逻辑