ENGINEERING NOTE 31 / 50 · CARD
支付Webhook应先验签，再信任内容
JSON格式正确并不能证明发送者身份。应用资金影响前，必须按提供方协议对要求的字节验签。
本文由 OPEN RAMBO 发布。工程方案和伪代码用于说明设计，不是现有产品 API 文档；示例数字均为演示。
保留被签名的字节
部分协议签原始正文。解析后重新序列化可能改变空白和字段顺序。应在Webhook路由配置正文处理，并用精确字节样例测试。不能从示例臆造签名格式。
处理重放风险
协议含签名时间戳时按文档容差检查。事件编号仍需独立去重。有效且新鲜的签名也可能是重复事件，不能二次入账。
谨慎轮换密钥
仅在协议支持时使用受控轮换重叠期，明确密钥编号与移除日期。密钥不进日志、前端包和客服截图。记录验签失败类别，不保存秘密或敏感正文。
示意流程
raw = request.raw_body
verify_documented_signature(raw, headers, active_keys)
deduplicate(event_id)
apply_business_effect_once()如何验收
测试改单字节、过期时间、有效事件重复和未知密钥，分别进入预期拒绝或去重路径。