Telegram webhook secret: что это и как правильно настроить

Это техническая настройка для сервера, на который Telegram отправляет новые сообщения, нажатия кнопок и другие события бота.

Но если бот перестал получать сообщения, вы переносите его на другой сервер или самостоятельно настраиваете webhook — тут уже полезно понимать, что именно Telegram отправляет вашему приложению и как сервер убеждается, что запрос ожидаемый.

Если вы здесь потому, что настраиваете webhook сами — готовьтесь, статья для вас.

Что такое webhook простыми словами

Telegram-боту нужно каким-то способом узнавать, что пользователь ему написал.

Есть два основных варианта.

Первый — getUpdates. Бот сам периодически спрашивает Telegram:

«Есть что-нибудь новое?»

Это называется polling.

Второй — webhook. Здесь уже Telegram сам отправляет HTTP-запрос на ваш сервер сразу после появления нового события.

Условно:

Пользователь написал боту

↓

Telegram получил сообщение

↓

Telegram отправил POST на ваш webhook

↓

Ваш сервер обработал Update

↓

Бот отвечает пользователю

Telegram официально называет getUpdates pull-механизмом, а webhook — push-механизмом. При установленном webhook новые Update отправляются HTTPS POST-запросами на указанный URL.

А что тогда такое webhook secret?

Сам webhook — это адрес, например:

https://example.ru/telegram/webhook

Но такой endpoint находится в интернете. Если его адрес известен, обратиться к нему технически может не только Telegram.

Для дополнительной проверки при setWebhook можно указать:

secret_token

После этого Telegram будет добавлять в каждый webhook-запрос HTTP-заголовок:

X-Telegram-Bot-Api-Secret-Token

а ваш сервер должен сравнить полученное значение со своим секретом.

Например:

Telegram

↓

POST /telegram/webhook

X-Telegram-Bot-Api-Secret-Token: my_secret_2026

↓

ваш сервер сравнивает secret

↓

совпадает → обрабатываем Update

не совпадает → отклоняем запрос

То есть webhook secret — не пароль пользователя и не токен самого бота. Это отдельное значение для проверки webhook-запросов.

Bot token и webhook secret — не одно и то же

Вот здесь легко запутаться.

Bot token

Выдаётся через BotFather.

Выглядит примерно так:

123456789:AAExample...

С ним приложение обращается к Telegram Bot API:

https://api.telegram.org/bot<BOT_TOKEN>/sendMessage

Человек, получивший bot token, потенциально получает возможность выполнять Bot API-запросы от имени вашего бота.

Поэтому bot token — настоящий секрет доступа, который нельзя публиковать.

Webhook secret

Его задаёте вы сами при регистрации webhook.

Например:

my_webhook_secret_2026

Он нужен вашему серверу для проверки входящего webhook-запроса.

Получается:

BOT TOKEN

ваш сервер → Telegram

WEBHOOK SECRET

Telegram → ваш сервер

Это разные значения и разные задачи.

Как установить webhook с secret_token

Webhook устанавливается методом setWebhook.

Упрощённый пример:

curl -X POST "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook" \
  -d "url=https://example.ru/telegram/webhook" \
  -d "secret_token=<WEBHOOK_SECRET>"

Настоящие токены в статьях, сообщениях, скриншотах и публичных репозиториях использовать не нужно — здесь специально стоят placeholders.

После успешного вызова Telegram сохранит URL webhook и начнёт передавать указанный secret в HTTP-заголовке каждого webhook-запроса.

Для secret_token сейчас разрешены:

A-Z

a-z

0-9

_

-

Длина — от 1 до 256 символов.

Поэтому строка вроде:

webfixer24_bot_prod_7F2k9X

подходит.

А пробелы и произвольные специальные символы использовать нельзя.

Как сервер проверяет webhook secret

Логика очень простая.

Сервер получает заголовок:

X-Telegram-Bot-Api-Secret-Token

и сравнивает его с секретом, который хранится у приложения.

Условно:

secret = request.headers.get(
    "X-Telegram-Bot-Api-Secret-Token"
)

if secret != WEBHOOK_SECRET:

return 403

После успешной проверки уже можно разбирать JSON Update.

Принцип:

получили POST

↓

проверили secret

↓

secret неверный → отказ

↓

secret правильный → разбираем Update

↓

обрабатываем сообщение / кнопку / событие

Сам secret лучше хранить не прямо в исходном коде, а в переменной окружения или другом серверном хранилище конфигурации.

Например:

TELEGRAM_WEBHOOK_SECRET=...

И тем более его не стоит коммитить в публичный GitHub.

Как узнать, установлен ли webhook

Для этого есть официальный метод:

getWebhookInfo

Запрос:

https://api.telegram.org/bot<BOT_TOKEN>/getWebhookInfo

В ответе особенно полезны несколько полей:

url

pending_update_count

last_error_date

last_error_message

ip_address

url показывает текущий webhook.

pending_update_count — сколько обновлений Telegram пока не смог доставить.

last_error_message — последнюю известную ошибку доставки.

И вот этот метод реально полезен при диагностике.

Если бот молчит, я бы смотрел getWebhookInfo раньше, чем начинал хаотично переписывать код.

Бот молчит: что смотреть в getWebhookInfo

Представим:

{
  "url": "https://example.ru/telegram/webhook",
  "pending_update_count": 47,
  "last_error_message": "..."
}

Очередь растёт.

Это сильный признак того, что Telegram получает обновления, но нормально передать их вашему endpoint не получается.

Дальше уже проверяем:

Telegram

↓

DNS

↓

HTTPS

↓

reverse proxy

↓

webhook route

↓

проверка secret

↓

код приложения

Именно в таком порядке обычно проще локализовать проблему.

Почему webhook может не работать

1. Установлен неправильный URL

Например, приложение реально слушает:

/telegram/webhook

а в Telegram зарегистрировано:

/telegram/webhooks

Одна буква — и бот молчит.

2. Сервер отклоняет webhook secret

Например, при setWebhook задан:

secret_A

а приложение сравнивает заголовок с:

secret_B

Telegram до сервера дошёл, но ваше приложение само отвечает отказом.

3. Проблема с HTTPS

Для обычного облачного Bot API webhook URL должен использовать HTTPS.

Telegram поддерживает webhook-порты:

443

80

88

8443

В большинстве обычных проектов проще использовать нормальный домен с действующим TLS-сертификатом и стандартный 443.

4. Endpoint отвечает ошибкой

Telegram ожидает успешный HTTP-ответ.

Если webhook endpoint возвращает не 2XX, Telegram считает доставку неуспешной и повторяет попытки некоторое время.

Поэтому нужно смотреть не только код бота, но и реальные HTTP status в логах сервера.

5. Вы одновременно ждёте getUpdates

После установки outgoing webhook метод getUpdates для получения обновлений работать не будет.

То есть схема:

webhook + getUpdates одновременно

— не способ «для надёжности».

Нужно выбрать механизм получения обновлений.

Как удалить webhook

Если нужно временно вернуться к polling, используется:

deleteWebhook

Либо webhook можно удалить, передав пустой url в setWebhook.

Отдельно существует параметр:

drop_pending_updates

Он позволяет удалить накопившиеся ожидающие обновления.

Но включать его автоматически при любой проблеме не стоит: можно намеренно выбросить сообщения, которые бот ещё не обработал.

Нужно ли прятать webhook URL?

Желательно не делать endpoint очевидным вроде:

/webhook

если архитектура позволяет использовать менее предсказуемый путь.

Secret path тоже может усложнить посторонние запросы к endpoint.

Но secret URL и secret_token решают немного разные задачи.

Если Bot API уже поддерживает secret_token, разумно проверять именно заголовок, а не считать необычный URL единственной защитой.

А при чём здесь Telegram Mini App?

Сам по себе Mini App и webhook — не одно и то же.

Mini App работает внутри Telegram как веб-приложение.

Webhook относится прежде всего к тому, как backend бота получает Bot API Updates.

Они вполне могут быть частями одного проекта:

Telegram

├── Bot

│ └── webhook → backend

│

└── Mini App

└── HTTPS/API → backend

Но наличие Mini App само по себе не означает, что вам обязательно нужно вручную работать с webhook secret.

Поэтому, если вы делаете Mini App и внезапно нашли статью про webhook, сначала выясните: проблема действительно в получении Bot API Updates или совсем в другой части приложения.

Что проверить, если webhook не работает

Короткий чек-лист:

1. Выполнить getWebhookInfo.
2. Проверить правильность url.
3. Посмотреть pending_update_count.
4. Посмотреть last_error_message.
5. Убедиться, что HTTPS работает снаружи.
6. Проверить HTTP status webhook endpoint.
7. Проверить X-Telegram-Bot-Api-Secret-Token.
8. Сравнить его с серверным WEBHOOK_SECRET.
9. Посмотреть application/server logs.
10. Убедиться, что вы не пытаетесь одновременно получать события через getUpdates.

Вот после этого обычно уже становится понятно, на каком участке перестали доходить обновления.