WooCommerce Webhook 會在訂單、商品、顧客或其他事件發生時，把通知主動送到指定網址。它適合連接 ERP、倉庫、CRM、會員系統及自動化工具，但接收端若沒有驗證簽署、去重和重試設計，可能造成重複出貨、漏單或偽造請求。
先定義要解決的事件
不要把所有資料都送到同一流程。先寫明觸發事件、接收系統、必要欄位及預期動作，例如訂單付款完成後建立倉庫工作，而不是籠統設定「訂單更新」便直接出貨。
選擇準確的 Topic
WooCommerce 可依訂單、商品、優惠券、顧客等資源建立、更新或刪除觸發，也可選擇 Action。Topic 過廣會在每次小變更都發送通知；Topic 過窄則可能漏掉真正需要的狀態轉換。
建立專用接收網址
接收端應使用 HTTPS，路徑只處理 Webhook，不要與一般表單或公開 API 共用。正式、測試和開發環境使用不同網址及秘密，避免測試訂單寫入正式 ERP 或發出真實通知。
設定獨立 Secret
Secret 用來產生傳送內容的雜湊簽署。為每個目的地使用長而隨機的獨立秘密，保存在伺服器秘密管理或受保護設定中，不要寫入前端程式、文章、截圖或公開版本庫。
在接收端驗證原始內容
驗證簽署時要使用收到的原始 request body，而不是先解析再重新序列化的 JSON。任何空格、編碼或欄位順序改變都可能令雜湊不同。簽署不正確時直接拒絕，並避免把完整秘密寫入日誌。
快速回應再背景處理
接收端應先完成基本驗證和排隊，再快速回傳成功狀態。庫存同步、寄信、產生文件或呼叫第三方 API 應由背景工作處理，否則長時間執行容易超時，令來源再次嘗試或判定失敗。
為事件加入去重機制
網絡重試、人工重送及接收端超時都可能帶來相同事件。以 Webhook、訂單、事件類型和版本組合建立唯一鍵；處理前查核是否完成，確保同一通知不會重複扣庫存或建立兩張發票。
不要依賴事件到達順序
不同通知可能延遲或亂序到達。接收端應比較訂單目前狀態、更新時間或版本，再決定是否執行，並在關鍵操作前向 WooCommerce API 重新讀取最新資料，而不是完全信任較舊的 payload。
限制接收端可以做的事
Webhook 專用服務只取得必要權限。若流程只需建立內部通知，就不應同時擁有退款、刪除商品或修改顧客的權限。把高風險動作拆成另一個需額外批准的工作。
記錄可追查的日誌
記錄接收時間、Topic、訂單識別、簽署結果、回應狀態、處理耗時及內部工作編號。顧客地址、電話、付款資料和 Secret 應遮罩。日誌要有保留期限，亦要能由訂單反查整條處理鏈。
用測試訂單驗證流程
在 staging 建立不同付款、取消、退款和失敗情境，確認每個事件只執行一次。也要故意讓接收端暫停、回傳錯誤及延遲，觀察重試、告警與補償流程是否符合預期。
了解自動停用條件
WooCommerce 官方文件指出，連續多次傳送失敗後 Webhook 可能被自動停用；非成功類回應會被視為失敗。不要只等待外部系統報錯，應監察 Webhook 狀態並在被停用時立即告警。
從 WooCommerce 日誌排查
到 WooCommerce > Status > Logs，篩選 Webhook delivery 相關記錄，查看目標網址、HTTP 狀態及錯誤時間。若來源顯示成功而接收端沒有資料，再依內部工作編號檢查排隊和背景處理。
安全地輪替 Secret
輪替時可讓接收端短時間同時接受新舊兩把 Secret，確認新設定已收到有效事件後才移除舊秘密。直接單邊更換容易造成所有通知驗證失敗，並觸發連續失敗停用。
建立補發與對帳程序
Webhook 不是唯一帳本。每日用 WooCommerce API 或匯出資料與 ERP、倉庫及付款系統對帳，找出漏單、重複和狀態差異。補發工具應指定事件與訂單，保留審計紀錄，避免全量盲目重播。
上線前檢查清單
確認 HTTPS、Topic、Secret、簽署驗證、快速回應、去重、亂序處理、最小權限、遮罩日誌、監察及對帳全部完成。先小量啟用並觀察，再逐步擴展到正式訂單流量。
參考資料
[WooCommerce 官方：Webhooks](https://woocommerce.com/document/webhooks/)
