Как установить вебхук Telegram-бота

С вебхуком Telegram сам отправляет каждое обновление на ваш HTTPS-адрес — не нужно опрашивать getUpdates. Разберём, как настроить его правильно и безопасно.

Сделайте это в пару кликов — без кода и сервера, прямо в браузере.

Открыть менеджер вебхука

Требования

Публичный HTTPS-адрес. Обычный HTTP не принимается.
Порт 443, 80, 88 или 8443.
Действительный TLS-сертификат (TLS 1.2+). Самоподписанный подойдёт, только если загрузить его публичный ключ.
Обработчик должен быстро отвечать HTTP 2xx, иначе Telegram повторяет запросы и обновления копятся.

Установка вебхука онлайн

Откройте Telegram Bot Manager и вставьте токен бота от @BotFather.
На вкладке «Вебхук» укажите URL вашего обработчика.
Нажмите «Сгенерировать», чтобы создать секретный токен, и сохраните его в конфиге сервера.
Выберите allowed_updates, если нужны только некоторые типы обновлений (или chat_member / реакции, которые по умолчанию выключены).
Нажмите «Установить вебхук». Блок состояния сразу покажет результат.

Параметры

Параметр	Что делает
`url`	HTTPS-адрес, на который приходят обновления в виде JSON POST-запросов.
`secret_token`	1–256 символов `A-Z a-z 0-9 _ -`, передаётся в заголовке `X-Telegram-Bot-Api-Secret-Token` каждого запроса.
`allowed_updates`	Типы получаемых обновлений. Пустой список = всё, кроме chat_member, message_reaction, message_reaction_count.
`max_connections`	Одновременные HTTPS-соединения, 1–100 (по умолчанию 40).
`ip_address`	Фиксированный IP вместо определения адреса через DNS.
`certificate`	Публичный ключ самоподписанного сертификата.
`drop_pending_updates`	Удалить обновления, ожидающие в очереди.

То же самое через 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"

Проверяйте секретный токен на сервере

Всегда сравнивайте заголовок со своим секретом и отклоняйте остальные запросы — сам 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 — смените порт или поставьте перед сервером reverse proxy.
Bad Request: bad webhook: Failed to resolve host — у домена нет публичной DNS-записи.
Bad Request: secret token contains unallowed characters — используйте только буквы, цифры, _ и -.