Headless Commerce Webhook 可靠性 QA 检查清单

Webhook endpoint 即使返回 200，也可能漏掉订单、重复扣减库存、用旧数据覆盖新客户信息，或让商品状态长期不同步。HTTP response 只能证明某个请求到达了某个 endpoint，不能证明业务事件已经完成验证、保存、处理和对账。

这份清单适合连接 storefront、commerce platform、CMS、ERP、OMS、仓库、搜索索引、CRM 或 analytics 的 Shopify 与 Headless Commerce 团队。可以用于上线前、集成变更后，或任何两个系统数据不一致的事故排查。

• 列出所有影响收入、可售性、履约、客户权限和搜索可见性的事件。
• 把传输成功、处理成功和下游业务成功分开定义。
• 分别指定 producer、endpoint、queue、consumer 和 reconciliation job 的负责人。
• 为每种事件定义可接受延迟和可容忍的数据丢失范围。

先建立表格，再开始写代码。为每个事件记录 producer、source-of-truth object、事件名称与版本、必填字段、顺序规则、destination、预期流量、timeout 和恢复路径，避免两个系统都以为自己拥有同一个字段。

覆盖创建、更新、取消、删除、退款、履约、库存、价格、发布与客户同意事件。标记哪些变更可以合并，哪些必须按顺序处理。商品描述更新可以容忍延迟，订单取消通常需要更严格的时效。

• 使用稳定的 event ID 和 object ID，不要只根据 timestamp 或 payload hash 去重。
• 记录 schema version，以及 consumer 收到未知字段或版本时的处理方式。
• 说明 payload 是完整 snapshot、partial update，还是仅用于触发 refetch 的通知。
• 明确订单、库存、价格、客户、履约和发布状态的 source of truth。
• 保存已移除敏感值的 sample payload，并清楚标记 edge case。

任何 Webhook 转成业务动作前都要验证。HMAC signature 通常需要原始 request body；如果先解析 JSON 再序列化，空格或顺序变化就可能导致错误验证。使用 timing-safe comparison 比较签名，并拒绝过期或格式错误的请求。

签名正确并不能阻止有效请求被 replay。处理前先保存 event ID、producer、接收时间和验证结果。去重记录的保留时间要覆盖 provider retry schedule 和团队自己的手动重放流程。

• 从文档指定的 header 读取签名，并根据完全一致的 raw bytes 验证。
• Secret rotation 期间，在受控窗口同时支持当前与上一个 secret。
• 拒绝不支持的 method、content type、超大 body、无效 timestamp 和错误签名。
• 不要记录完整的客户、支付、token 或认证 payload。
• 对外返回通用失败信息，对内记录可用于调查的 correlation ID。

Commerce provider 会重试事件，网络也会产生重复请求，运营人员还会重放失败事件。同一个事件必须能够安全接收多次。使用 producer 与 event ID 建立持久化处理记录，并尽量把业务写入和 processed state 放进同一个 transaction。

幂等也适用于下游动作。邮件、退款、库存预留、shipment 创建或商品索引如果执行两次都会产生真实成本。使用 outbox 或 action key，防止 retried handler 再次执行不可逆操作。

• 把同一个有效事件发送 2 次、5 次和 20 次，确认只产生一个业务结果。
• 测试乱序事件，并比较 version、sequence 或 source updated time。
• 除非业务规则明确允许，否则不要让旧 update 覆盖新状态。
• 使用 atomic write、unique constraint 或 compare-and-swap，不要依赖内存 flag。
• 把 duplicate 和 stale event 记录为预期处理结果，不要静默忽略。

公开 endpoint 应完成验证、envelope 校验、事件持久化、enqueue，然后在 provider timeout 内响应。慢速 API、图片处理、搜索索引、邮件和 ERP 更新应交给 background worker，减少 provider retry，也避免流量高峰耗尽 Web server。

重试前先分类失败。Rate limit、network timeout 和临时 upstream error 可能恢复；schema 无效、缺少必填映射、权限禁止和 destination record 已删除，通常需要 dead-letter path 或人工判断，而不是反复请求。

• 使用带 jitter 的 exponential backoff，并记录明确的最大尝试次数。
• 遵守 provider rate-limit header，并为每个 destination 设置 concurrency limit。
• 保存 attempt count、next attempt time、last error class 和 correlation ID。
• 把耗尽重试的事件送进 dead-letter queue，并保留诊断与重放所需上下文。
• 用正常事件量的 2 倍和 10 倍测试 queue backlog 行为。

监控业务数据的新鲜度，而不只是 endpoint uptime。Endpoint 正常但 worker 停滞，仍可能隐藏数小时的商品或订单更新缺失。Dashboard 应按事件类型与 destination 显示 received、verified、rejected、queued、processed、retried、dead-lettered 和 reconciled 数量。

Alert threshold 要根据业务影响设置。单个 newsletter event 失败可以等待，持续增长的订单 queue 或过期库存 feed 则需要快速升级。Alert 应链接 runbook，并显示最早受影响事件、backlog age、影响范围和安全恢复动作。

• 追踪从 source event 到下游状态确认的 p50、p95 和最大延迟。
• 为 queue age、retry rate、signature failure、dead-letter growth 和 reconciliation drift 告警。
• 对成功事件进行 end-to-end 抽样，让静默 mapping failure 也能被发现。
• 围绕 event ID、object ID、destination、attempt 和 deployment version 建立结构化日志。
• 上线 7 天和 30 天后复查告警，减少噪音但不要隐藏真实失败模式。

Webhook 是通知机制，不是完整 audit ledger。增加定时 reconciliation，把下游记录与权威系统比较。Job 应发现 missing object、stale version、total conflict、orphaned record，以及已接收但没有产生预期状态的事件。

先覆盖收入与可售性链路：订单、退款、履约、库存、价格、发布状态和客户权限。明确修复是自动执行、等待批准，还是只生成报告。在字段 ownership 尚未清楚前，不要让 reconciliation job 直接覆盖数据。

• 高频执行最近变更的小范围检查，定期执行更广的历史 backfill。
• 比较 count、ID、version、total、timestamp 和 state transition，不要只检查 row 是否存在。
• 把修复记录成新的可审计 action，并分配独立 idempotency key。
• 用故意丢弃、重复、延迟和损坏的事件测试 reconciliation。
• 输出 drift report，包含 severity、owner、repair status 和受影响客户或订单。