Webhook

Webhook 用于及时通知状态变化，但它不是唯一事实来源。你的系统必须能处理重复、乱序、延迟和暂时丢失的事件，并可用 Query API 主动对账。

推荐处理顺序

1. 读取原始请求 body。
2. 校验 PSP 签名和时间戳；不要对解析后重新序列化的 JSON 验签。
3. 使用事件 ID 做持久化去重。
4. 在本地事务内记录事件并提交待处理任务。
5. 尽快返回 2xx，把耗时业务处理放到异步消费者。
6. 状态跳跃或数据冲突时调用 Query API 校准。

状态机原则

• 不依赖事件到达顺序。
• 终态不可被较早的非终态事件回退。
• 同一事件重复投递应返回成功，而不是再次执行业务副作用。
• 金额、币种、商户订单号和账户必须与本地订单匹配后才能入账。

支付分类

代收、代付及信用卡生命周期事件的 data.classification 只包含创建时固化的 classification_status、payment_category、payment_method 和 rail_variant。 它不包含 runtime taxonomy version；目录 tuple 后续变为 inactive 只阻止新订单， 不会改写、取消或中断已接受订单。classification_schema_version 是 Webhook payload 结构版本，仍用于事件合同治理，与 taxonomy 无关。

响应时间

payment.intent.canceled 的 data 可包含 intent_id、invoice_number、merchant_order_id、provider_transaction_id、cancel_reason 和 canceled_at。历史事件中的部分引用可能为空；在商户账户范围内优先用 intent_id 或 merchant_order_id 关联，不要求一定存在渠道流水号。

验签、持久化并入队后立即返回成功。不要在 Webhook 请求线程中调用下游发货、短信、邮件或长事务。

失败恢复

非 2xx 响应会触发重试。持续失败时应通过告警发现，并由定时对账任务使用 Query API 补齐状态。完整事件结构见商户 Webhook API 参考。