收不到 webhook，或驗籤失敗

webhook 問題大多落在兩類：投遞根本沒到達你的伺服器，或到達了但驗籤失敗。請按下面對應的清單逐條排查。

投遞沒有到達

1. 該端點訂閱了這個事件所在的分組嗎？ 在控制台裡訂閱是按分組而非單個事件選擇的，共三類：支付事件（payment_order.*、payment.*）、商家訂閱事件（end_user_subscription.*、end_user_invoice.*）與運維事件（address.pool.low 以及 agent.action.* 審批）。只訂閱了支付事件的端點不會收到訂閱類或運維/Agent 事件，反之亦然。三類都不勾是不允許的；三類都勾表示“全部事件”，含將來新增的型別。（API 的 enabled_events 欄位技術上可攜帶任意子集，但控制台的分組模型無法表達任意子集。在控制台儲存一個自定義子集會把它擴成整組。）

2. 你的伺服器是否在 10 秒內返回了 2xx？ 任何非 2xx 狀態、網路錯誤，或 10 秒內無回應都算失敗。處理函式在回應前就做了大量實際工作是常見原因。先返回 200，再非同步處理。

3. 檢視投遞日誌。 每次嘗試都會記錄 response_status、response_duration_ms、error_message、attempts、next_retry_at 以及 status（pending / succeeded / failed / dead_letter）。這通常能立刻看出問題是否出在你這一側。

4. 把重試也算進去。 失敗的投遞按下面的曲線重試，到第 6 次進入死信佇列：

   嘗試次數	延遲
   1	30 秒
   2	60 秒
   3	5 分鐘
   4	30 分鐘
   5	2 小時
   6+	死信佇列

5. 修復後重放。 重放介面（以及面板上的重放按鈕）會入隊一條全新的投遞記錄，原始審計日誌會被保留。用 replay-dead-letters 排空在你的端點宕機期間落入死信佇列的投遞。

驗籤失敗

1. 針對原始 body 驗籤。 在任何 JSON 解析或重新序列化之前，對你收到的精確位元組計算簽名。會先解析再 re-stringify body 的框架會改變它從而破壞簽名。這是最常見的單一原因。

2. 從正確的請求頭讀取簽名。 使用 SDK 的 SIGNATURE_HEADER 常量，而不要硬編碼欄位名。

3. 使用正確的 secret。 secret 僅在建立和輪換時返回。如果沒存下來，輪換一次拿新的。

4. 輪換期間同時接受兩個 secret。 輪換後，舊 secret 會與新 secret 並存有效 24 小時。把兩者都傳給驗籤器，讓灰度過程中在途的投遞不會失敗：

   import { SIGNATURE_HEADER, verifySignature } from '@stableops/api-sdk/webhooks'
   
   const result = verifySignature({
     secrets: [currentSecret, previousSecret], // 24 小時重疊期內兩者都有效
     header: request.headers.get(SIGNATURE_HEADER) ?? undefined,
     rawBody,
   })
   
   if (!result.ok) {
     console.error('Invalid signature:', result.reason)
     // 拒絕該請求
   }

相關

• Webhooks
• Webhook 驗籤 SDK
• 支付事件參考