Как включить и отключить вебхук в Telegram: подробное руководство

Кратко: что такое вебхук и когда он нужен

• Вебхук: Telegram сам отправляет HTTP‑запросы на ваш URL при каждом апдейте. Требует публичный HTTPS и доступность сервера.
• Polling: ваш бот периодически сам запрашивает апдейты у Telegram. Работает без публичного HTTPS, но менее реактивен и требует фонового процесса.

Как включить вебхук (setWebhook)

curl -X POST "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook" \
     -H "Content-Type: application/json" \
     -d '{"url":"https://example.com/telegram-webhook"}'

curl -X POST "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook" \
     -H "Content-Type: application/json" \
     -d '{
           "url": "https://example.com/telegram-webhook",
           "secret_token": "<RANDOM_32_64_CHARS>",
           "drop_pending_updates": false,
           "max_connections": 40,
           "allowed_updates": ["message","callback_query","chat_member","my_chat_member"]
         }'

• secret_token: Telegram пришлет его в заголовке X-Telegram-Bot-Api-Secret-Token — проверяйте на стороне сервера.
• drop_pending_updates: если true, старая очередь апдейтов будет сброшена при установке вебхука.
• max_connections: до 100, оптимально 20–50 при высокой нагрузке.
• allowed_updates: ограничьте типы событий для снижения нагрузки.

Проверить статус вебхука

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

Как отключить вебхук (deleteWebhook)

curl -X POST "https://api.telegram.org/bot<BOT_TOKEN>/deleteWebhook"

# Сбросить все накопленные апдейты
curl -X POST "https://api.telegram.org/bot<BOT_TOKEN>/deleteWebhook?drop_pending_updates=true"

Нюансы и частые проблемы

1) HTTPS и SSL

• Домен обязателен с валидным SSL‑сертификатом (Let’s Encrypt — ок). Самоподписанные не подходят.
• Сертификат должен совпадать с доменом и не быть просроченным.
• Проверяйте цепочку доверия (full chain). Ошибки TLS приводят к last_error_message в getWebhookInfo.

2) Доступность URL и таймаут

• Telegram ограничивает время ответа ~10 секунд. Возвращайте 200 как можно быстрее, тяжелую обработку — в очередь/фоновую задачу.
• URL должен быть доступен из интернета без IP‑фильтров. Если есть WAF/файрвол, разрешите IP Telegram (см. оф. доки, IP‑пулы меняются).

3) Очередь апдейтов и дубликаты

• Большая pending_update_count = ваш обработчик не успевает. Увеличьте max_connections, оптимизируйте код, используйте асинхронную очередь.
• При миграции polling → webhook задайте drop_pending_updates=true, чтобы не получить старые сообщения повторно.

4) Переезд домена/SSL замена

• При смене домена/сертификата сделайте deleteWebhook, затем новый setWebhook.
• Проверьте редиректы: URL вебхука должен возвращать 200, а не 301/302 на другой хост без SNI.

5) Заголовки безопасности

• Проверяйте X-Telegram-Bot-Api-Secret-Token при использовании secret_token.
• Ограничьте метод только на POST, проверьте Content-Type: application/json.

6) Ограничения и лимиты

• Учитывайте лимиты Telegram Bot API (RPS). Пулы воркеров/очереди сообщений помогают не упираться в API‑лимиты при массовых рассылках.

7) IPv6 и прокси

• Если сайт доступен по IPv6 — убедитесь, что сервер действительно принимает трафик. Иначе отключите AAAA‑запись, если не используете.
• При использовании Cloudflare/прокси проверьте, что тело запроса не модифицируется и не урезается.

Интеграция с Bothost

• Вспомогательная статья: «Настройка авторизации через Telegram» — раздел про webhook.
• Примеры API в проекте:

• Для Git‑автодеплоя используйте WEBHOOK_SETUP.md и api/webhook.php (это про GitHub/GitLab webhooks, не путать с Telegram, но удобно для CI/CD ваших ботов).

• Настраивать secret_token в setWebhook и сверять его на своей стороне.
• Логировать запросы вебхука в отдельный файл (например, data/webhook.log) с маскированием чувствительных данных.
• Отдавать быстрый 200 и уносить бизнес‑логику в очередь.

Частые ошибки и решения

• «Conflict: can't use getUpdates method while webhook is active» — при активном вебхуке getUpdates не работает. Решение: сначала отключите вебхук, затем переходите на polling:

• «Bad Request: bad webhook: failed to resolve host or invalid URL» — проверьте корректность HTTPS‑URL, наличие публичного DNS A/AAAA.
• «Bad Request: webhook can be set up only on ports 443, 80, 88 or 8443» — используйте один из разрешенных портов.
• last_error_message в getWebhookInfo: ошибки TLS/таймаута/сетевого доступа. Проверяйте SSL‑цепочку и логи сервера.
• pending_update_count растет — ваш обработчик медленный, увеличьте параллельность и оптимизируйте код.
• Вебхук установлен, но бот «молчит» — убедитесь, что ваш обработчик возвращает 200 OK без долгих блокировок.

• Домен с валидным SSL (Let’s Encrypt/доверенный CA)
• URL вебхука отдает 200 OK (быстрый ответ < 1–2 сек)
• Настроен secret_token и проверка заголовка
• Логи включены и ротация настроена
• Очередь/воркеры для тяжелых задач
• allowed_updates ограничены до нужных типов
• getWebhookInfo показывает корректный URL и pending_update_count близок к 0

# Установить вебхук
curl -X POST "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook" \
     -H "Content-Type: application/json" \
     -d '{"url":"https://example.com/telegram-webhook"}'

# Проверить статус
curl "https://api.telegram.org/bot<BOT_TOKEN>/getWebhookInfo"

# Отключить вебхук
curl -X POST "https://api.telegram.org/bot<BOT_TOKEN>/deleteWebhook"

# Отключить и сбросить очередь
curl -X POST "https://api.telegram.org/bot<BOT_TOKEN>/deleteWebhook?drop_pending_updates=true"