Вебхук для телеграм-бота: налаштування setWebhook, перевірка та видалення
Вебхук телеграм-бота — це HTTPS-адреса вашого сервера, на яку Telegram сам надсилає POST-запит із кожним новим апдейтом. Вмикається він одним викликом setWebhook, перевіряється через getWebhookInfo, а видаляється методом deleteWebhook. Нижче — вимоги до сервера, готові команди curl, обробники з перевіркою secret_token на Python і Node.js та розбір типових помилок, зокрема з n8n на localhost.
Вебхук чи getUpdates: що обрати
| Параметр | getUpdates (long polling) | Вебхук |
|---|---|---|
| Хто ініціює | Бот сам опитує Telegram | Telegram надсилає апдейти на ваш сервер |
| Що потрібно | Будь-яка машина з інтернетом, навіть за NAT | Публічна HTTPS-адреса й сертифікат |
| Коли зручно | Розробка, невеликі боти, немає домену | Продакшн, serverless, навантаження з піками |
Способи взаємовиключні: поки вебхук встановлено, getUpdates не працює. В обох випадках Telegram зберігає недоставлені апдейти не довше 24 годин.
Вимоги до сервера для вебхука
- Лише HTTPS із TLS 1.2 або новішим — на будь-якому порту. Звичайний HTTP хмарний Bot API не приймає, це дозволено тільки на локальному Bot API сервері.
- Порти 443, 80, 88 або 8443. Інші не працюють. Якщо порт не 443, вкажіть його в URL:
https://bot.example.com:8443/telegram/webhook. - Сертифікат, у якого CN або SAN збігається з доменом, із повним ланцюжком проміжних сертифікатів. Безкоштовний Let's Encrypt підходить. Самопідписаний теж можна, але його треба завантажити в
setWebhook. - IPv4. IPv6 для вебхуків поки не підтримується.
- Без редиректів: відповідь 301 чи 302 Telegram не виконає.
- Якщо фільтруєте трафік за IP, пропускайте підмережі
149.154.160.0/20і91.108.4.0/22та звіряйтеся з офіційним гайдом про вебхуки — діапазони можуть змінюватися.
Як встановити вебхук через setWebhook
| Параметр | Навіщо потрібен |
|---|---|
url | HTTPS-адреса обробника. Порожній рядок видаляє вебхук |
secret_token | 1–256 символів A-Z, a-z, 0-9, _, -; приходить у заголовку X-Telegram-Bot-Api-Secret-Token |
allowed_updates | Які типи апдейтів надсилати, наприклад ["message", "callback_query"] |
drop_pending_updates | true — відкинути апдейти, що накопичилися |
max_connections | Одночасних з'єднань із сервером: 1–100, за замовчуванням 40 |
certificate | Публічний ключ самопідписаного сертифіката (лише файлом, multipart) |
ip_address | Фіксована IP-адреса замість отриманої з DNS |
export BOT_TOKEN="123456789:AAEexampleTokenReplaceWithYours"
export WEBHOOK_SECRET="$(openssl rand -hex 32)" # збережіть — він потрібен обробнику
curl -s "https://api.telegram.org/bot$BOT_TOKEN/setWebhook" \
--data-urlencode "url=https://bot.example.com/telegram/webhook" \
-d "secret_token=$WEBHOOK_SECRET" \
--data-urlencode 'allowed_updates=["message","callback_query"]' \
-d drop_pending_updates=true \
-d max_connections=40
{"ok": true, "result": true, "description": "Webhook was set"}
Зверніть увагу: якщо не передати allowed_updates, збережеться попередній список. Порожній список означає всі типи, крім chat_member, message_reaction і message_reaction_count. Спробувати без термінала можна в Bot API Tester на методі setWebhook.
Із самопідписаним сертифікатом у CN можна вказати IP-адресу сервера, а публічний ключ передати файлом:
openssl req -newkey rsa:2048 -sha256 -nodes -keyout private.key -x509 -days 365 \
-out public.pem -subj "/CN=203.0.113.10"
curl -s "https://api.telegram.org/bot$BOT_TOKEN/setWebhook" \
-F "url=https://203.0.113.10:8443/telegram/webhook" \
-F "certificate=@public.pem" \
-F "secret_token=$WEBHOOK_SECRET"
Перевірка вебхука: getWebhookInfo
curl -s "https://api.telegram.org/bot$BOT_TOKEN/getWebhookInfo"
{
"ok": true,
"result": {
"url": "https://bot.example.com/telegram/webhook",
"has_custom_certificate": false,
"pending_update_count": 12,
"last_error_date": 1793275800,
"last_error_message": "Wrong response from the webhook: 502 Bad Gateway",
"max_connections": 40,
"allowed_updates": ["message", "callback_query"]
}
}
urlпорожній — вебхук не встановлено, бот працює черезgetUpdates;pending_update_countзростає — Telegram не може доставити апдейти, вони накопичуються в черзі;last_error_messageіlast_error_date— остання помилка доставки: код відповіді вашого сервера, відмова в з'єднанні, тайм-аут або проблема з SSL;has_custom_certificate—true, якщо завантажено власний сертифікат.
Ту саму перевірку зручно запускати в getWebhookInfo у Bot API Tester, щойно апдейти перестають приходити.
Обробник вебхука з перевіркою secret_token
Адреса вебхука публічна, тож будь-хто може надіслати на неї підроблений апдейт. Заголовок X-Telegram-Bot-Api-Secret-Token відсікає такі запити: порівнюйте його із секретом за сталий час і відповідайте 403 на чужі запити.
Python, FastAPI (pip install fastapi uvicorn) або Node.js, Express (npm i express):
import hmac
import os
from fastapi import FastAPI, Header, HTTPException, Request
WEBHOOK_SECRET = os.environ["WEBHOOK_SECRET"]
app = FastAPI()
@app.post("/telegram/webhook")
async def telegram_webhook(
request: Request,
x_telegram_bot_api_secret_token: str | None = Header(default=None),
):
received = (x_telegram_bot_api_secret_token or "").encode()
if not hmac.compare_digest(received, WEBHOOK_SECRET.encode()):
raise HTTPException(status_code=403)
update = await request.json()
# покладіть апдейт у чергу й одразу поверніть 200
print("update", update["update_id"])
return {"ok": True}import crypto from 'node:crypto';
import express from 'express';
const expected = Buffer.from(process.env.WEBHOOK_SECRET);
const app = express();
app.use(express.json());
app.post('/telegram/webhook', (req, res) => {
const received = Buffer.from(req.get('X-Telegram-Bot-Api-Secret-Token') ?? '');
if (received.length !== expected.length || !crypto.timingSafeEqual(received, expected)) {
return res.sendStatus(403);
}
res.sendStatus(200); // спершу відповідь Telegram
handleUpdate(req.body).catch(console.error); // потім обробка
});
async function handleUpdate(update) {
console.log('update', update.update_id);
}
app.listen(8000); // TLS термінує nginx або Caddy перед застосункомПорт 8000 не входить до чотирьох дозволених, тому застосунок має стояти за nginx чи Caddy, які приймають HTTPS на 443 і проксіюють запити далі. Стежте, щоб секрет на сервері й у setWebhook збігався: інакше ваш же обробник відповідатиме 403, а Telegram повторюватиме доставку.
Відповідайте 2xx швидко
- Будь-яку відповідь, крім 2xx, Telegram вважає невдачею і повторює запит, а апдейти тим часом накопичуються в
pending_update_count. - Відповідайте 200 одразу, а запити до бази, зовнішніх API і нейромереж виконуйте у фоні або через чергу.
- Апдейти, які бота не цікавлять, теж підтверджуйте відповіддю 200, інакше вони приходитимуть знову.
- Зберігайте оброблені
update_id: повторна доставка можлива, і дублікати краще відсікати.
Бонус: у відповіді на вебхук можна одразу викликати метод Bot API. Поверніть JSON із полем method і параметрами — Telegram виконає запит, але дізнатися його результат ви не зможете:
{"method": "sendMessage", "chat_id": 123456789, "text": "Прийнято!"}
Як видалити вебхук телеграм-бота
Щоб повернутися до getUpdates, викличте deleteWebhook. Параметр drop_pending_updates=true заразом відкине накопичені апдейти — це зручно, якщо бот довго не працював і не повинен відповідати на старі повідомлення:
curl -s "https://api.telegram.org/bot$BOT_TOKEN/deleteWebhook?drop_pending_updates=true"
Без цього параметра черга збережеться, і getUpdates віддасть її повністю. Той самий ефект, що й deleteWebhook, дає setWebhook із порожнім url.
Типові помилки вебхука
Bad Request: bad webhook: An HTTPS URL must be provided for webhook — у url передано адресу з http:// або без схеми. Потрібен саме https:// і публічний домен чи IP.
409 Conflict під час виклику getUpdates — вебхук встановлено, і long polling заблоковано. Якщо вебхук поставив інший сервіс (наприклад, n8n), а вам потрібен polling, викличте deleteWebhook. Якщо ж потрібен вебхук, зупиніть скрипт, який викликає getUpdates.
n8n на localhost. Telegram-тригер у n8n реєструє вебхук через setWebhook, а адреса на кшталт http://localhost:5678 не підходить двічі: це не HTTPS, і Telegram не може достукатися до вашого комп'ютера. Потрібна публічна HTTPS-адреса: n8n на сервері з доменом за nginx чи Caddy із сертифікатом або тунель на зразок cloudflared чи ngrok. Публічну адресу треба передати самій n8n (зазвичай через змінну оточення WEBHOOK_URL), щоб вона реєструвала в Telegram саме її.
Один бот — один вебхук. Якщо два сервіси чи два воркфлоу використовують той самий токен, вони перезаписують вебхук один одному. Дайте кожному сервісу окремого бота.
Вебхук встановлено, але апдейти не приходять. Дивіться last_error_message у getWebhookInfo. Типові причини: непідтримуваний порт, неповний ланцюжок сертифікатів, редирект, обробник падає з 5xx або файрвол не пропускає підмережі Telegram. Перевірити TLS із зовнішньої машини допоможе curl -v https://bot.example.com/telegram/webhook.
Вебхук приймає апдейти, а відповіді надсилаються як завжди — через sendMessage, докладніше в гайді як надіслати повідомлення через бота. Якщо бот лише створюється, почніть з інструкції зі створення бота, а з проблемами токена зазирніть у гайд токен бота Telegram. Про обмеження на кількість з'єднань і зберігання апдейтів — в огляді ліміти Telegram Bot API.
Поширені запитання
Як видалити вебхук телеграм-бота?
Викличте https://api.telegram.org/bot<token>/deleteWebhook. З параметром drop_pending_updates=true заразом видаляться апдейти, що накопичилися. Після цього знову працює getUpdates.
Чи можна використовувати вебхук і getUpdates одночасно?
Ні, ці способи взаємовиключні. Поки вебхук встановлено, getUpdates повертає 409 Conflict.
Які порти підтримує вебхук Telegram?
Лише 443, 80, 88 і 8443, причому HTTPS обов'язковий на будь-якому з них. Порт, відмінний від 443, вказують просто в URL: https://example.com:8443/webhook.
Чи потрібен платний SSL-сертифікат для вебхука?
Ні. Підійде безкоштовний сертифікат, наприклад Let's Encrypt, або самопідписаний — його треба завантажити в параметрі certificate під час виклику setWebhook.
Як перевірити, що запит на вебхук надіслав саме Telegram?
Передайте secret_token у setWebhook: Telegram додаватиме його в заголовок X-Telegram-Bot-Api-Secret-Token кожного запиту. Порівнюйте заголовок з очікуваним значенням і відхиляйте запити без нього.
Чому Telegram надсилає той самий апдейт повторно?
Ваш сервер відповів не 2xx або не відповів вчасно, і Telegram повторив доставку. Відповідайте 200 одразу, важку обробку виносьте у фон, а дублікати відсікайте за update_id.
Читайте також
Як створити бота в Телеграм: від @BotFather до першого повідомлення
Як створити бота в Телеграм: реєстрація в @BotFather, токен, перевірка через getMe, перше повідомлення на curl і Python, команди та опис бота.
Що нового в Telegram Bot API 10.0–10.5: налаштування бота, віджети, rich-повідомлення, ефемерні повідомлення й гостьовий режим
Що нового в Telegram Bot API 10.0–10.5: setMySettings і BotFullInfo, HTML-віджети, rich- та ефемерні повідомлення, гостьовий режим — з прикладами.
Ліміти Telegram Bot API: повідомлення на секунду, помилка 429 і розміри файлів
Ліміти Telegram Bot API в одному місці: повідомлення на секунду, помилка 429 і retry_after, платні розсилки, розміри файлів, довжина тексту й підпису.
Як надіслати повідомлення через бота Telegram: sendMessage, розмітка й кнопки
Як надіслати повідомлення через бота телеграм: sendMessage на curl, Python і JavaScript, parse_mode HTML і MarkdownV2, кнопки та помилки 400, 403, 429.
Токен бота Telegram: як отримати, де знайти, як перевірити й відкликати
Токен бота Телеграм: як отримати його в @BotFather, де знайти токен наявного бота, як перевірити через getMe і що робити, якщо токен витік.
Як дізнатися chat id у Телеграм: користувач, група, канал і тема форуму
Як дізнатися chat id у Телеграм через getUpdates: особистий чат, група, супергрупа, канал і тема форуму. Формати id з -100 і що робити з порожнім result.
Тестовий сервер Telegram: як тестувати бота в тестовому середовищі
Тестовий сервер Telegram для ботів: вхід у тестове середовище, створення тестового бота, запити до Bot API через /test/ і перемикач TEST у тестері.
Віджети Telegram для сайту: вхід через Telegram, вбудовування постів, коментарі й кнопка «Поділитися»
Вхід через Telegram на сайті: новий Telegram Login (OIDC), старий Login Widget із перевіркою hash, вбудовування постів, коментарі та кнопка «Поділитися».
TelegramWidget JavaScript API: властивості, події, коди помилок і ліміти
Довідник TelegramWidget API: властивості, request(), події, коди помилок, CSS-змінні, widget_query та answerWidgetQuery, а також усі ліміти віджетів.
Приклади віджетів Telegram: готовий HTML і код бота на Python
Робочі приклади віджетів Telegram із повним кодом: картка замовлення, лічильник із запитами widget_query, спільне живе опитування та прев'ю в браузері.
Віджети Telegram: інтерактивний HTML просто в повідомленнях бота
Віджети Telegram у Bot API 10.4: що це, як працюють sendWidget, chat_data і public_data, де віджети доступні зараз і чим вони відрізняються від Mini Apps.
Тестування Telegram Mini App: від браузера до налагодження на телефоні
Тестування Telegram Mini App крок за кроком: mock-режим у браузері, HTTPS-тунель для localhost, тестове середовище, DevTools на телефоні та initData.