Auto-sync: 2026-04-16 13:01

wiki/concepts/Telegram-Webhook.md

@@ -0,0 +1,37 @@
+---
+title: "Telegram Webhook"
+type: concept
+tags: [telegram, webhook, bot, integration]
+---
+
+## 定义
+Telegram Webhook 是一种服务端回调机制：Telegram 服务器在用户发送消息后，将 HTTP POST 请求推送至用户配置的公网 HTTPS URL。
+
+## 工作原理
+1. 在 Telegram BotFather 创建机器人，获得 Bot Token
+2. 向 Telegram API 设置 Webhook URL：`https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://your-domain.com/webhook`
+3. 用户发送消息 → Telegram → POST 到配置的 URL
+4. 服务端处理请求，可返回响应消息
+
+## 核心约束
+- **必须使用 HTTPS**：Telegram 强制要求，不支持 HTTP 或自签名证书
+- **公网可达**：Telegram 服务器必须能访问该 URL
+- **响应时间限制**：Telegram 要求 5 秒内响应，否则视为失败
+
+## n8n 集成
+- [[n8n]] Telegram Trigger 节点自动处理 Webhook 订阅
+- 常见错误：`Bad Request: bad webhook: An HTTPS URL must be provided for webhook`
+- 解决方案：设置 [[WEBHOOK_URL]] 环境变量为公网 HTTPS 地址
+- 参见 [[n8n-Telegram-Trigger-HTTPS配置修复]]
+
+## 与 Polling 对比
+| 特性 | Webhook | Polling |
+|------|---------|---------|
+| 实时性 | 立即推送 | 轮询间隔决定 |
+| 服务器负载 | 低 | 高（持续请求） |
+| 需要公网 | 是 | 否 |
+| 部署复杂度 | 高（需要 HTTPS） | 低 |
+
+## 相关
+- [[Telegram]]: 即时通讯平台
+- [[WEBHOOK_URL]]: n8n 环境变量