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 或 worker 已经完成工作。
如果 url 为空，先确认这个 bot 原本是否应该使用 webhook。如果确实要更换接收模式，请参考独立的 getUpdates 与 setWebhook 切换操作指南。本文只排查现有 webhook 的投递链路。
结合积压趋势和错误时间判断
先记录基线，再发送一条 bot 应当能接收的受控测试消息，然后重新检查状态。观测时间写入自己的运维记录，不要把它伪装成 Telegram 返回字段。
| 观察结果 | 可能说明什么 | 下一步 |
|---|---|---|
| 积压增加，投递错误时间持续更新 | 观测期间仍在投递失败 | 检查公网入口、TLS、路由和 HTTP 响应日志 |
| 积压减少，错误时间仍是旧值 | 投递可能正在恢复 | 确认测试更新已保存并完成处理 |
| 积压为零，但业务没有动作 | 仅凭数量无法定位故障 | 检查存储、内部队列、worker 和路由规则 |
| 积压不为零，但没有新错误 | 单次快照不足以下结论 | 再次观测，并与接收端流量对照 |
| 同步错误时间更新 | 报告的是 Telegram 更新同步问题 | 保留证据，不要默认换证书就能修复 |
这些是调查分支，不是自动诊断。积压下降也不保证恢复完整：Telegram 明确说明，收到的更新最多保留 24 小时。长时间中断应视为可能的数据缺口，而不是可以无限期补收的队列。
沿请求链路逐层检查
用最新错误描述缩小范围，再用自己的日志验证：
- 公网目标： 对照生产环境的域名和路径，检查 DNS 与入口路由；存在
ip_address时也一起核对。 - TLS： 检查证书有效性、主机名覆盖和实际提供的证书链。Telegram 官方 webhook 指南提供了证书排查说明。不要降低验证要求来掩盖配置错误。
- HTTP 处理： 检查公网入口真正返回的状态，而不只是应用日志。代理可能在 handler 执行前就已响应；浏览器能打开页面也不能证明 webhook POST 路径可用。
- 持久化： 确认接收的更新已经写入可靠存储。建议先验证请求来源、提交到持久化收件箱或队列，再返回确认；耗时的外部调用放到后续处理。
- 业务处理： 沿已保存的更新追踪 worker。使用幂等处理，避免重复投递造成重复业务动作。
Telegram 文档说明，webhook 请求返回非 2XY 状态时会重试，并在合理次数后停止。这不是一个公开固定的重试时间表，不要根据猜测的间隔承诺恢复时限。
不删除积压的恢复验收
修复已确认的故障后，再发一条受控消息，核对完整链路：接收请求、持久化记录、预期业务动作。观察积压是否消退，以及是否出现新的投递错误。
不要把 drop_pending_updates 当成修复手段。官方定义是丢弃待处理更新，它不能修好 TLS，也不能修复 worker。也不要盲目提高 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 跑通发送，再用标准事件把所有入站消息接回业务系统。