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 小時。長時間中斷應視為可能的資料缺口，不是可以無限期補收的佇列。

沿請求路徑逐層檢查

先根據最新錯誤描述縮小範圍，再以自己的記錄佐證：

1. 公開目標： 核對正式環境的網域及路徑，檢查 DNS 和入口路由；有 ip_address 時亦一併比較。
2. TLS： 檢查憑證有效性、主機名稱涵蓋範圍及實際提供的憑證鏈。Telegram 官方 webhook 指南提供相關排查方法。不要降低驗證要求來掩蓋設定錯誤。
3. HTTP 處理： 查看公開入口真正回傳的狀態，不只看應用程式日誌。代理可能在 handler 執行前已回應；瀏覽器能開啟頁面，也不能證明 webhook POST 路徑可用。
4. 持久化： 確認更新進入可靠儲存。建議先驗證請求來源、提交至持久化收件箱或佇列，再回覆確認；耗時的外部操作留待後續處理。
5. 業務處理： 沿已儲存更新追蹤背景工作，以冪等處理避免重複傳送造成重複業務動作。

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。

• Telegram Bot API：WebhookInfo、setWebhook 及 Getting updates
• Telegram webhook 排查指南