如何设置 Telegram 机器人 Webhook

使用 Webhook 后，Telegram 会把每条更新推送到你的 HTTPS 地址，无需轮询 getUpdates。下面介绍如何正确、安全地进行设置。

要求

• 公网可访问的 HTTPS 地址，不支持普通 HTTP。
• 端口为 443、80、88 或 8443。
• 有效的 TLS 证书（TLS 1.2+）。自签名证书需上传其公钥才能使用。
• 服务器必须快速返回 HTTP 2xx，否则 Telegram 会重试，更新会不断积压。

在线设置 Webhook

1. 打开 Telegram Bot Manager，粘贴从 @BotFather 获取的机器人 Token。
2. 在 Webhook 选项卡中填写处理程序的 URL。
3. 点击生成创建 Secret Token，并保存到服务器配置中。
4. 如果只需要部分更新类型（或需要默认关闭的 chat_member / 表情回应），请选择 allowed_updates。
5. 点击设置 Webhook，状态区域会立即显示结果。

参数

使用 curl

curl -X POST "https://api.telegram.org/bot$BOT_TOKEN/setWebhook" \
  --form-string "url=https://example.com/telegram/webhook" \
  --form-string "secret_token=$WEBHOOK_SECRET" \
  --form-string 'allowed_updates=["message","callback_query"]' \
  --form-string "max_connections=40"

使用自签名证书：

curl -X POST "https://api.telegram.org/bot$BOT_TOKEN/setWebhook" \
  --form-string "url=https://203.0.113.10:8443/webhook" \
  -F "certificate=@public.pem"

在服务器上校验 Secret Token

务必将请求头与你的密钥比对并拒绝其他请求——仅靠 Webhook URL 并不安全。

// Node.js (Express): reject requests without the right secret
app.post('/telegram/webhook', (req, res) => {
  if (req.get('X-Telegram-Bot-Api-Secret-Token') !== process.env.WEBHOOK_SECRET) {
    return res.sendStatus(401);
  }
  // handle req.body (Update) ...
  res.sendStatus(200);
});

常见错误

• Bad Request: bad webhook: An HTTPS URL must be provided for webhook——请使用 https://。
• Bad Request: bad webhook: Webhook can be set up only on ports 80, 88, 443 or 8443——更换端口，或在前面放置反向代理。
• Bad Request: bad webhook: Failed to resolve host——域名没有公网 DNS 记录。
• Bad Request: secret token contains unallowed characters——只能使用字母、数字、_ 和 -。