Андэграм
Андэграм
Читать в Telegram

Как тестировать Telegram‑webhooks локально

Андэграм

Помогаю авторам и бизнесу расти в Telegram без воды: понятные стратегии, пошаговые контент‑планы, разборы ошибок и рабочие инструменты. Пишу простым языком и даю конкретику, которую можно применить сегодня. Если хотите запустить канал, выбрать нишу и стабильно набирать подписчиков — вы в нужном месте.

Открыть в TelegramДругие публикации
telegramwebhookngrok

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

Что нужно для локального теста webhook

  • локально запущенный бот, например на localhost:3000
  • публичный HTTPS URL
  • настройка setWebhook у Telegram
  • логирование входящих запросов

Webhook должен быть доступен по HTTPS, а ваш сервер — быстро отвечать 200 OK, даже если основная обработка занимает время.

1. ngrok — самый популярный вариант 🚀

Плюсы: быстрый старт, удобный интерфейс, инспектор запросов.
Минусы: бесплатные URL могут меняться, есть лимиты.

Как запустить:

  • поднимите бота локально на нужном порту
  • выполните: ngrok http 3000
  • получите публичный URL вида https://xxxx.ngrok-free.app
  • установите webhook: 
    https://api.telegram.org/bot/setWebhook?url=https://xxxx.ngrok-free.app/webhook

Почему его любят:

  • видно все входящие запросы
  • легко проверять headers и payload
  • удобно для быстрой отладки ошибок 400/500

2. cloudflared — стабильный и легкий вариант ☁️

Cloudflared Tunnel часто выбирают как альтернативу ngrok.

Плюсы: простой запуск, хорошая стабильность, часто меньше ограничений в бытовом использовании.
Минусы: интерфейс отладки скромнее.

Команда:

  • cloudflared tunnel --url http://localhost:3000

Сервис выдаст публичный адрес вида https://random.trycloudflare.com. Его также указываете в setWebhook.

Cloudflared особенно удобен, если нужен быстрый временный HTTPS-домен без лишней настройки.

3. Другие туннели: localtunnel, zrok, localhost.run 🛠️

Если ngrok и cloudflared не подходят, есть альтернативы:

  • localtunnel — очень простой запуск, но стабильность может плавать
  • zrok — современный инструмент с хорошими сценариями шаринга
  • localhost.run — минималистичный SSH-подход без тяжелой настройки

Их стоит рассматривать как запасной вариант, если нужен тест “здесь и сейчас”.

Частые ошибки при тестировании webhook ⚠️

  • Неверный путь — Telegram шлет запросы на /webhook, а сервер слушает другой route
  • Порт не тот — туннель проксирует не на тот локальный порт
  • Нет 200 OK — Telegram считает endpoint проблемным
  • Медленный ответ — сначала отдайте 200, потом обрабатывайте задачу
  • Старый webhook — после смены URL заново вызывайте setWebhook
  • Нет проверки — используйте getWebhookInfo, чтобы увидеть статус и ошибки

Полезные методы:

  • setWebhook — установить адрес
  • deleteWebhook — сбросить старый
  • getWebhookInfo — проверить, что Telegram видит ваш endpoint

Что выбрать

  • Для новичка: ngrok
  • Для легкого и быстрого теста: cloudflared
  • Для экспериментов и запасного плана: localtunnel и аналоги

Главное правило: туннель — это временное решение для разработки, а не замена продакшен-инфраструктуре. Для локальной отладки этого более чем достаточно. ✅

Посмотрите подборку Телеграм-каналов — там собраны полезные ресурсы для разработчиков, авторов ботов и тех, кто строит проекты внутри Telegram.

👁 Подборки каналов
🤖 Каталог ботов и приложений
✈️ Навигация

Читайте так же