Подключение вебхука
Вебхук отправляет события бота на ваш HTTPS-адрес. Постоянно вызывать getUpdates не нужно: Шляпс сам делает POST-запрос при появлении события.
Для одного бота выберите один способ получения событий: вебхук или getUpdates. Сначала остановите long polling, затем подключайте вебхук. Если старый запрос ещё выполняется, настройка вернёт 409; повторите её после завершения запроса.
Что подготовить
Нужен доступный из интернета HTTPS-адрес на порту 443 с обычным доверенным сертификатом. Поддерживаются публичные IPv4. Локальные адреса, IPv6, собственные недоверенные сертификаты и HTTP-переадресации не поддерживаются.
Задайте отдельный секрет в переменной KODARI_WEBHOOK_SECRET. Допустимы латинские буквы, цифры, _ и -, длина от 1 до 256 символов. Например, случайное значение можно получить командой:
python -c "import secrets; print(secrets.token_urlsafe(32))"
Сохраните значение у получателя и передайте его в setWebhook. Это отдельный секрет для проверки входящих запросов. Токен бота KODARI_BOT_TOKEN получателю вебхука не отправляется.
Подключение через BotFather
Откройте /mybots в BotFather, выберите бота и нажмите «Вебхук». В меню доступны адрес, очередь, последняя ошибка, подключение и отключение. После ввода HTTPS-адреса BotFather покажет новый секрет для заголовка X-Shlyaps-Bot-Api-Secret-Token. Сохраните его у получателя. Очередь при смене адреса и отключении сохраняется.
Если работает getUpdates, сначала остановите его. При 409 из-за текущей доставки повторите действие чуть позже. Фильтр типов событий можно изменить через Bot API или SDK.
Подключение через HTTP API
Установите переменные KODARI_BOT_TOKEN и KODARI_WEBHOOK_SECRET, замените адрес в примере своим:
import os
import requests
response = requests.post(
"https://api.kodari.ru/msg/bot.php?method=setWebhook",
headers={"Authorization": f"Bearer {os.environ['KODARI_BOT_TOKEN']}"},
json={
"url": "https://bot.example.com/shlyaps/webhook",
"secret_token": os.environ["KODARI_WEBHOOK_SECRET"],
"allowed_updates": ["message", "callback_query"],
"drop_pending_updates": False,
},
timeout=15,
)
response.raise_for_status()
print(response.json())
Успешный ответ: {"ok": true, "result": true}. Он подтверждает сохранение настройки. Доступность получателя проверяется при доставке первого события.
Переданные allowed_updates применяются к ожидающим и новым событиям вебхука. Пустой массив включает все поддерживаемые типы. Если параметр не передан, сохраняется прежний выбор. drop_pending_updates: true удаляет ожидающие события, поэтому включайте его только когда старая очередь больше не нужна.
Как выглядит запрос
POST /shlyaps/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Shlyaps-Webhook/1.0
X-Shlyaps-Bot-Api-Secret-Token: your_webhook_secret
{
"update_id": 123,
"message": {
"message_id": 456,
"chat": {"id": 789, "type": "direct"},
"from": {"id": 42, "is_bot": false, "first_name": "Иван"},
"text": "/start"
}
}
Тело содержит один объект Update без внешнего массива и без полей ok и result. Формат событий совпадает с объектами из getUpdates.
Проверьте секретный заголовок, сохраните событие и верните любой HTTP 2xx. Для ответа в чат вызовите sendMessage отдельным запросом Bot API. Тело HTTP-ответа вебхука как команда Bot API не выполняется.
IP отправителя
Доставка идёт с публичных IP фронтов Шляпса. Сейчас это 139.100.234.153 и 135.106.162.125; разрешите оба адреса, если используете список разрешённых IP. Проверяйте также секретный заголовок.
Прямой запасной маршрут с внутреннего сервера не используется. Когда маршрут через фронт недоступен, события остаются в очереди до следующей попытки.
Проверка и отключение
curl "https://api.kodari.ru/msg/bot.php?method=getWebhookInfo" \
-H "Authorization: Bearer $KODARI_BOT_TOKEN"
Смотрите pending_update_count, last_success_date, last_error_date и last_error_message. Для возврата к long polling отключите вебхук:
curl -X POST "https://api.kodari.ru/msg/bot.php?method=deleteWebhook" \
-H "Authorization: Bearer $KODARI_BOT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"drop_pending_updates":false}'
Ожидающие события сохранятся, и их можно будет получить через getUpdates. При 409 дождитесь завершения текущей доставки и повторите запрос.
В pykodaribot 0.5.0 есть set_webhook, delete_webhook, get_webhook_info и готовый приёмник aiohttp. Вебхуки Python SDK. Подробности: методы вебхуков, доставка и обработчик.