使用 SDK 内置的 WebhookHandler
我们强烈建议使用 SDK 方法webhook().handleWebhook(),它会自动处理:
- 签名校验
- JSON 解析与事件路由
- 响应体构建与签名
幂等处理
Waffo 可能会多次投递同一个事件。请确保你的处理逻辑具备幂等性:按最终状态处理,不依赖投递顺序
Webhook 是异步分发的通知,商户收到多个相关回调的顺序不保证。尤其是订阅首期场景中,SUBSCRIPTION_STATUS_NOTIFICATION 和 SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION 都可能发送,请不要依赖这两个回调的到达顺序。
- 不要按回调到达顺序更新最终业务状态
- 以
subscriptionId、事件 ID 或业务订单 ID 做幂等去重 - 如果同时订阅
SUBSCRIPTION_STATUS_NOTIFICATION和SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION,收到任一回调后调用POST /api/v1/subscription/inquiry查询最终状态,再进入统一的订阅回调处理逻辑
快速响应
- SDK 会在 handler 执行完成后自动构建响应
- 耗时操作(例如发送邮件或更新外部系统)应异步处理
- 如果在 handler 中抛出异常,SDK 会自动返回失败响应
安全
- 始终校验
X-SIGNATURE(由 SDK 自动处理) - 使用 HTTPS 端点
- 在处理事件前先校验签名——在校验通过之前不要执行任何业务逻辑
- 响应必须包含
X-SIGNATUREheader(由 SDK 自动处理)