Webhook endpoint 回 200，不代表資料已正確同步；回 500 也不代表 Shopify 會永遠重送。可靠 handler 要先驗證來源、保存事件、快速 acknowledgment，再非同步處理，並用 reconciliation 補 delivery 和程式漏失。
Shopify 的 header、retry 和版本行為會更新，實作前核對當期官方文件。
使用 raw body 驗證 HMAC
在 JSON parse 前取得原始 request bytes，以 app client secret 計算 HMAC-SHA256、Base64，和 X-Shopify-Hmac-Sha256 做 constant-time comparison。Header name 當 case-insensitive，簽章失敗回 401/適當錯誤且不處理 payload。
Framework middleware 若先轉字串或改 whitespace，會讓 HMAC 失敗。建立真實 raw fixture 測成功、錯誤 secret、body 修改和缺 header。
快速回應再處理
驗證、基本 schema 和寫入 durable queue 成功後立即回 2xx。ERP call、Email、圖片和複雜 business logic 放 worker。Queue 寫入失敗則不要假裝成功，讓 retry 或告警處理。
Shopify 對 timeout 和非 2xx 有 retry/移除規則，監看當期 delivery metrics；不要把重試當永久儲存。
用 delivery ID 去重
保存 X-Shopify-Webhook-Id 或官方指定 delivery ID，使用唯一 constraint。相同 delivery 重送只 acknowledgment，不重複副作用。若多 topic 由同 merchant action 產生，可用 event ID/correlation 協助分析，但各 delivery 仍有自己的處理。
Ledger 保存 shop、topic、API version、triggered_at、received_at、status 和 attempts，payload 依資料最小化與 retention。
不依賴事件順序
Shopify 不保證同 topic 或跨 topic ordering。使用 payload updated_at、triggered time、resource version 或重新 fetch latest；舊事件不得覆蓋新狀態。Create 晚於 update、delete 後晚到 update 都需案例。
對完整狀態 resource，優先將事件當「需要同步」通知，再讀權威 API；對不可重建副作用則用狀態機和 ledger。
API version 和 schema 管理
記錄 X-Shopify-API-Version，handler 支援部署中可能並存的版本。Subscription version 升級前用 fixture/contract tests，比較欄位、enum 和 nullability。未知欄位安全忽略，必要欄位缺失進 DLQ。
不要讓 payload 直接散布到所有內部服務，先轉成內部 versioned event。
Reconciliation 是必要退路
官方明確建議不要只依賴 webhook。定期查 updated resources，使用 watermark 加 overlap，和 local/下游逐 ID 比較。Handler downtime、subscription removed、bug 或錯誤 2xx 都能被補回。
提供營運手動 reconcile，顯示範圍、dry run、差異與安全 replay。可靠性架構可參考 API 同步失敗補救。
隱私 compliance webhook 特別處理
Customer data request、customer redact、shop redact 等 mandatory topics 依 Shopify app 要求訂閱、驗證和在期限內處理。資料搜尋範圍涵蓋下游、log、queue 和備份政策；法務需求由合規 owner 核准。
無效 HMAC 不執行刪除。有效請求建立 audit，但不在 log 暴露完整個資。
監控 subscription 和 delivery
Metrics 看 request、HMAC failure、2xx/non-2xx、response latency、queue age、processing failure、retry、DLQ、API version 和 reconciliation gap。Subscription 被移除或 endpoint/secret 改變需立即告警。
部署 endpoint 時保留舊、新位址過渡，因 retry 可能仍送到事件觸發時的舊 endpoint。憑證輪替設雙版本或明確窗口。
用故障案例驗收
測 duplicate、out-of-order、stale payload、large payload、timeout、queue outage、worker crash、rate limit、token revoke、API version、delete、privacy request 和 endpoint migration。每個案例確認副作用一次、狀態可見、能 replay/reconcile。
Webhook 驗證完成的證據，不只是一段 HMAC 程式；還包括 queue、去重、順序、補漏、監控和合規事件都能在故障時維持一致。