Проще говоря, webhook - это входной адрес для событий Telegram-бота. Пользователь написал сообщение, Telegram сделал HTTP-запрос на ваш сервер, backend проверил update, вызвал нужный сценарий или AI-агента и отправил ответ через Bot API.
Webhook обычно используют в production, потому что он быстрее и экономнее polling. Polling подходит для локальной разработки: приложение само спрашивает Telegram, есть ли новые сообщения. Webhook работает наоборот: Telegram сам доставляет события на ваш сервер.
Для Telegram webhook нужен публичный HTTPS-адрес. Endpoint должен быстро принимать запросы, проверять, что событие действительно пришло от Telegram, обрабатывать повторные доставки, логировать update id и не падать, если AI-ответ генерируется долго. Часто backend сначала кладет событие в очередь, сразу возвращает 200 OK, а обработку делает асинхронно.
В AI-ботах webhook - только входная точка. Дальше начинается логика: определить пользователя, восстановить agent state, проверить ACL, обработать команду или callback query, вызвать LLM, tool calling, CRM, базу знаний или workflow, а затем отправить ответ пользователю.
В production важно не смешивать секреты и публичный код. Bot token нельзя хранить в репозитории, webhook URL лучше защищать secret token, update id стоит использовать для idempotency, а ошибки отправлять в monitoring. Если Telegram повторно пришлет update, бот не должен дважды создать сделку, списать оплату или отправить одно и то же сообщение.
Примеры
- Пользователь пишет /start. Telegram отправляет update на webhook, backend создает сессию и отправляет приветственное сообщение.
- Пользователь нажимает inline-кнопку. Webhook получает callback query, а бот переводит диалог в следующий шаг сценария.
- Клиент отправляет PDF. Telegram присылает update с file_id, backend скачивает файл через Bot API и запускает обработку документа.
- AI-ответ может генерироваться 20 секунд. Backend кладет update в очередь, возвращает Telegram 200 OK и отправляет ответ позже отдельным запросом.
- Telegram повторно доставил update из-за сетевой ошибки. Idempotency по update_id не дает боту создать дубль заявки.
Где используется
- production-запуск Telegram-бота
- подключение AI-агента к Telegram
- обработка команд, сообщений и inline-кнопок
- прием файлов, фото и голосовых сообщений
- запуск workflow в n8n, Make или backend API
- создание заявок и сделок из Telegram
- модерация комментариев и каналов
- асинхронная обработка долгих AI-сценариев
- логирование и мониторинг событий бота
Связанные термины
Частые вопросы
Что такое Telegram webhook простыми словами?
Это адрес вашего сервера, куда Telegram отправляет события бота: сообщения, команды, нажатия кнопок и файлы.
Чем webhook отличается от polling?
При polling приложение само постоянно спрашивает Telegram о новых событиях. При webhook Telegram сам отправляет события на ваш HTTPS-endpoint, поэтому это удобнее для production.
Что нужно для Telegram webhook?
Нужен публичный HTTPS-адрес, backend endpoint, bot token, настройка webhook через Bot API, обработка updates и логика ответа пользователю.
Почему webhook должен быстро отвечать?
Если endpoint долго не отвечает или падает, Telegram может повторить доставку update. Поэтому долгие AI-задачи лучше отправлять в очередь и сразу возвращать 200 OK.
Как защитить Telegram webhook?
Нужно хранить bot token вне кода, использовать secret token или проверку источника, логировать update_id, делать idempotency, ограничивать права бота и не выполнять опасные действия без подтверждения.
