Telegram getWebhookInfo：排查待傳遞更新與 webhook 錯誤
Telegram webhook 看起來卡住時，先查看 getWebhookInfo，不要急著變更設定。pending_update_count 是等待傳遞的更新數，不是應用程式尚未完成的工作數。應搭配 last_error_date、last_error_message 與接收端日誌判斷。積壓歸零不表示業務流程完成，而保留錯誤紀錄也不一定表示端點現在仍然失敗。
重點整理
- 先在現有 webhook 模式下診斷；切換接收方式是另一項作業。
- 比較多次狀態快照與錯誤時間，不用單一數字判定健康狀態。
- 分別驗證請求抵達、持久化儲存和業務處理。
- 不要為了讓監控顯示正常而丟棄待傳遞更新。
getWebhookInfo 能告訴你什麼
Telegram Bot API 官方參考說明，getWebhookInfo 不需要參數，會回傳 WebhookInfo 物件。透過現有 Bot API 用戶端，在可信任環境中呼叫；不要將 bot token 或含敏感資訊的 webhook URL 寫入共用日誌或截圖。
| 欄位 | 官方定義 | 診斷用途 |
|---|---|---|
url | webhook 網址；未設定時為空 | 確認目標屬於正確環境 |
pending_update_count | 等待傳遞的更新數量 | 比較積壓正在增加或減少 |
last_error_date | 選填，最近一次 webhook 傳遞錯誤的 Unix 時間 | 判斷錯誤是否發生在修復之前 |
last_error_message | 選填，該錯誤的可讀描述 | 確定調查方向，不當成固定錯誤列舉 |
ip_address | 選填，目前使用的 webhook IP 位址 | 對照預期的公開目標 |
last_synchronization_error_date | 選填，與 Telegram 資料中心同步可用更新時最近一次錯誤的時間 | 與無法連到接收端的錯誤分開判斷 |
已設定 URL 不代表端點可連線。選填錯誤欄位不存在，也無法證明 CRM 或背景工作已完成。
若 url 為空，先確認這個 bot 原本是否應使用 webhook。若真正需求是切換模式，請參考 getUpdates 與 setWebhook 切換指南。本文只診斷現有 webhook 的傳遞路徑。
一起觀察積壓趨勢與錯誤時間
先記錄基準狀態，再傳送一則 bot 應能收到的受控測試訊息，接著重新查看狀態。觀測時間應記在自己的維運紀錄中，不要把它當成 Telegram 回傳欄位。
| 觀測結果 | 可能代表什麼 | 下一步 |
|---|---|---|
| 積壓增加，傳遞錯誤時間持續更新 | 觀測期間仍有傳遞失敗 | 查公開入口、TLS、路由與 HTTP 回應日誌 |
| 積壓減少，錯誤時間維持舊值 | 傳遞可能正在恢復 | 確認測試更新已儲存並處理 |
| 積壓為零，卻沒有業務動作 | 數量本身不足以定位 | 查儲存、內部佇列、背景工作與路由規則 |
| 積壓非零，但沒有新錯誤 | 單次快照不足以下結論 | 再次觀測並比對接收端流量 |
| 同步錯誤時間更新 | 回報的是 Telegram 更新同步問題 | 保留證據，不要假設換憑證即可修復 |
這些只是調查方向，不是自動診斷。積壓下降也不保證完整恢復：Telegram 明確說明，更新最多保留 24 小時。長時間中斷應視為可能的資料缺口，而非能無限期補收的佇列。
沿請求路徑逐層檢查
根據最新錯誤描述縮小範圍，再以自己的紀錄佐證：
- 公開目標： 比對正式環境網域與路徑，檢查 DNS 和入口路由；若有
ip_address，也一起核對。 - TLS： 檢查憑證有效性、主機名稱涵蓋範圍，以及實際提供的憑證鏈。Telegram 官方 webhook 指南有相關排查說明。不要降低驗證要求來掩蓋設定問題。
- HTTP 處理： 查看公開入口真正回傳的狀態，不只看應用程式日誌。代理可能在 handler 執行前就回應；瀏覽器能開啟頁面，也不表示 webhook POST 路徑正常。
- 持久化： 確認更新進入可靠儲存。建議先驗證請求來源、提交至持久化收件匣或佇列，再回覆確認；耗時外部作業留給後續處理。
- 業務處理： 沿儲存的更新追蹤背景工作，透過冪等處理避免重複傳遞造成重複動作。
Telegram 文件說明，webhook 回應不是 2XY 時會重試，並在合理次數後停止。這不是公開固定的重試時程，不應用猜測的間隔承諾復原時間。
不刪除積壓的復原驗收
修復已確認的問題後，再傳一則受控訊息，驗證接收請求、持久化紀錄及預期下游動作。觀察積壓是否消退，以及是否出現新的傳遞錯誤。
不要把 drop_pending_updates 當成修復工具。官方定義是丟棄待傳遞更新，它不能修好 TLS 或背景工作。也不要盲目增加 max_connections：它控制 webhook 同時連線數，不代表應用程式能安全處理對應負載。
無法解釋的中斷區間仍須保留核對工作。HTTP 確認只代表該邊界的傳遞成功，不代表整個業務流程成功。
UnifyPort 的定位與限制
getWebhookInfo 觀察的是 Telegram Bot API webhook，不會檢查 UnifyPort 接收端，也不能透過不同身分取回 bot 的積壓。身分選擇可參考 Telegram Bot API webhook 與統一入站 webhook 比較。
UnifyPort 非官方介面使用獨立事件契約，包括 message.received。webhook 傳遞參考說明 X-Device-Event-Id、確認回應與重試規則。設定 signing_secret 後，使用 HMAC-SHA256 對 X-Device-Timestamp、一個句點與原始請求本文計算簽章，以核驗 X-Device-Signature。
請將這條路徑與 Bot API 狀態分開監控。UnifyPort 沒有讀取訊息歷史的 REST API，也不保證重播漏收的資料；可靠入站儲存仍是接收端的責任。業務需要 bot 身分時，繼續使用官方 Bot API。
常見問題
pending_update_count 是未讀訊息數嗎？
不是。它是等待傳遞的更新數，不是聊天室未讀狀態，也不是尚未完成的工作數。
last_error_message 還存在，就表示 webhook 仍有故障嗎？
不一定。它描述最近一次傳遞錯誤，應搭配錯誤時間、後續觀測和受控端到端測試判斷。
積壓歸零後可以結案嗎？
不能只憑這點。還要確認儲存與處理完成，並檢查可能超出 Telegram 保留期間的中斷。
下一步與來源
現有 Telegram bot 應先查看 getWebhookInfo 並追蹤測試更新，再變更設定。透過已連接的訊息帳號接收事件時，先閱讀 UnifyPort 傳遞契約。
官方參考核對日期：2026-09-18。
讓訊息接入變成一條穩定的產品管線。
先用統一 API 跑通傳送，再用標準事件把所有入站訊息接回業務系統。