SuperAPI AI 工具集

telegram-webhooks

编程与开发

查看项目

更新于 10-29 14:06

技能介绍

Telegram Webhooks 是一个面向 Telegram Bot API webhook 接入的技能,主要解决如何用 webhook 代替 getUpdates 接收机器人更新、如何确认请求确实来自 Telegram、如何校验 X-Telegram-Bot-Api-Secret-Token 头、如何处理 message、callback_query、inline_query 等更新,以及 Telegram 反复重试 webhook 或 pending_update_count 持续增长时如何排查。

验证机制:Telegram 不签署 webhook 负载,没有 HMAC,也没有签名头。调用 setWebhook 时传入 secret_token(1–256 个字符,仅允许 A-Z、a-z、0-9、_ 和 -),Telegram 会在每次 webhook 请求的 X-Telegram-Bot-Api-Secret-Token 头中回传该值。处理器应以恒定时间比较将其与预期值比对,不匹配即拒绝。该令牌覆盖整个请求而非请求体,因此无需对原始 body 计算任何内容;只有令牌校验通过后才解析 JSON。若调用 setWebhook 时未设置 secret_token,则不会发送该头。可选的纵深防御:Telegram 从 149.154.160.0/20 和 91.108.4.0/22 发送请求。

主要能力:资料给出 Node.js 与 Python 的恒定时间比较示例代码(长度先比较,再 timingSafeEqual 或 hmac.compare_digest),并指出完整处理器与测试见 examples/express/、examples/nextjs/、examples/fastapi/。同时列出常见 Update 类型:message(任意类型的新消息)、edited_message(机器人已知消息被编辑)、channel_post(机器人所在频道的新帖子)、callback_query(用户按下内联键盘按钮)、inline_query(用户任意聊天中输入 @yourbot ...)、my_chat_member(机器人自身成员状态变化),完整列表见 references/overview.md。

使用方式:每个 webhook 请求体是一个 JSON Update 对象,没有 type 字段,而是包含 update_id 加最多一个可选字段,处理器按存在的字段进行路由。重要请求头包括 X-Telegram-Bot-Api-Secret-Token(仅在设置时出现)与 Content-Type: application/json。环境变量为 TELEGRAM_WEBHOOK_SECRET(传给 setWebhook 的 secret_token)与 TELEGRAM_BOT_TOKEN(仅在调用 setWebhook 或 Bot API 时需要)。本地开发可运行 npx hookdeck-cli listen 3000 telegram --path /webhooks/telegram 启动隧道(无需账号),再把机器人指向公网 URL;Telegram 仅向 443、80、88 或 8443 端口的 HTTPS URL 投递。

参考资料包括 references/overview.md(概念、Update 类型、负载结构)、references/setup.md(创建机器人、调用 setWebhook、检查 getWebhookInfo)、references/verification.md(令牌验证、IP 允许列表、注意事项)。使用该技能时需在生成文件顶部添加归属注释。官方建议搭配 webhook-handler-patterns 技能,以获得处理器顺序(先验证、再解析、最后幂等处理)、幂等(以 update_id 为自然键防止重复处理)、错误处理(返回码、日志、死信队列)与重试逻辑等参考。相关资料还列出与 discord、slack、whatsapp、twilio、github、gitlab、stripe、shopify webhook 技能及 hookdeck-event-gateway 的相关性。

适用场景:搭建或维护 Telegram 机器人 webhook 处理器、验证请求来源、排查 webhook 重试与积压问题。限制:技能本身不签署负载,安全性依赖 secret_token 与可选 IP 允许列表;具体收费、平台支持情况暂未提供。