使用 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 端点
- 在处理事件前先校验签名——在校验通过之前不要执行任何业务逻辑