---
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 环境变量