監視與失敗時的對應

Webhook 監視警報無效信件故障對應

本文的對象
適用於在正式環境運用 Webhook 的開發者、運用負責人。說明投放狀況的確認方法、應監視的指標、故障發生時的復原步驟。

Webhook 是「運作時很安靜」的機制。正因如此，難以察覺問題正在發生，等察覺到時，數天分的事件已經漏失了，這種情況很容易發生。正式運用中能動的監視不可或缺。

開發者入口的投放紀錄

在開發者入口 → 應用程式 → Webhook → 該端點 → 「投放紀錄」分頁，可確認過去 30 天的投放結果。

顯示的資訊

投放日時、事件 ID、事件種類
最終狀態（成功 / 重試中 / 無效信件）
各試行的 HTTP 狀態碼、回應時間、回應主體（開頭 1KB）
「重新投放」按鈕（可手動重送）

篩選

狀態（僅成功／僅失敗／僅無效信件）
事件種類
期間（過去 24 小時／7 天／30 天）
事件 ID／接收 URL 部分一致

應監視的指標

是正式運用中最低限度應留意的指標。除了可在開發者入口的「Webhook 儀表板」確認外，也建議匯入自家的監視基礎。

指標	警報閾值的範例	意義
成功率（最近 1 小時）	低於 99% 則通知	端點的可用性
P95 回應時間	超過 3 秒則警告	處理效能的劣化偵測
無效信件件數（24 小時）	發生 1 件也通知	漏失事件的存在
重送中件數	超過 100 件則警告	接收端的持續性失敗
逾時發生率	超過 1% 則警告	接收端處理過重的徵兆

接收端應持有的指標

除了發送端的監視外，接收端也取下列指標的話原因特定會更快。

接收件數（依事件種類）
簽章驗證失敗次數（增加的話有密鑰不一致或攻擊的可能性）
冪等性略過件數（重送是否沒有增加的參考）
處理時間直方圖（是否接近 10 秒逾時）
業務處理錯誤率（會成為重送迴圈的原因）

警報通知對象的設計

警報以「能察覺」外加「能對應」的形式設計。

營業時間中：Slack 的運用頻道
夜間、假日：以 PagerDuty / Opsgenie 等通知待命負責人
輕度的警告：彙整至每日摘要郵件
無效信件發生：即時通知＋週次審查

無效信件的重新投放

7 次自動重送失敗的事件會作為「無效信件」保存。修正原因後，可用下列步驟重新投放。

在投放紀錄選擇「無效信件」篩選
個別點擊「重新投放」按鈕，或複選後「批次重新投放」
在投放紀錄確認結果

無效信件自投放起保持 30 天。超過 30 天會消失，因此請在此之前對應，或以 API 重新取得過去資料。

常見故障模式與因應

1. 全 Webhook 以 `5xx` 失敗中

確認接收端伺服器是否宕機
近期的部署為原因的可能性 → 檢討回滾
復原後，將無效信件「批次重新投放」

2. 僅一部分事件種類失敗

該事件用的處理邏輯可能有 bug
從投放紀錄的回應主體確認堆疊追蹤
在接收端日誌搜尋該 event_id

3. `401`（簽章驗證失敗）增加了

重新產生密鑰後不久，舊密鑰是否還沒運作
環境變數的反映漏失（忘記重啟）
是否搞錯正式／預備的密鑰

4. 逾時頻發

接收端的處理重 → 變更為投入內部佇列的設計
下游 DB 或外部 API 的延遲 → 暫時將該處理旁路
接收端點的擴充不足 → 增加實例數

5. Webhook 完全沒來

端點是否變成「無效」
訂閱事件是否正確選擇
對象店鋪篩選中自己是否沒被排除
接收 URL 是否可從外部到達（是否變成在公司內 VPN 內）

定期維護的檢查清單

建議每月 1 次左右，審查下列項目。

☐ 過去 1 個月的無效信件件數與原因
☐ 成功率的推移（是否劣化）
☐ P95 回應時間的推移
☐ 密鑰的最終更新日（每年 1 次輪替為參考）
☐ 不需要的端點的刪除
☐ 訂閱事件的整理（移除沒使用的）

向支援的洽詢

無法特定原因時，或懷疑 ReceiptRoller 端的故障時，請向開發者社群或支援窗口洽詢。洽詢時附上下列資訊會較順利。

應用程式 ID（用戶端 ID）與端點 ID
事象發生的日時範圍（UTC 或 JST 明記）
受影響的 event_id 數個
接收端的回應碼與日誌摘錄