Доставка и пример обработчика
Шляпс отправляет один POST с JSON на каждый Update. Любой ответ HTTP 2xx подтверждает получение. Переадресация, ответ 4xx/5xx, ошибка DNS, TLS или соединения оставляют событие в очереди.
Подключение ограничено пятью секундами, весь HTTP-запрос десятью. При неудаче повтор начинается через 5 секунд, затем через 10, 20, 40 секунд и далее с увеличением задержки до одного часа. Очередь автоматически из-за ошибки не удаляется.
Порядок и повторные события
Для одного бота события идут последовательно. Пока первое не подтверждено, следующие ждут. Если HTTP-ответ потерялся после обработки события, оно придёт снова с тем же update_id.
Сохраняйте update_id и не выполняйте одно и то же действие повторно. Если один обработчик принимает нескольких ботов, учитывайте пару из идентификатора бота и update_id, поскольку номера событий принадлежат отдельному боту.
Возвращайте 2xx после записи события в постоянную очередь. Долгую работу выполняйте отдельным процессом. При ошибке записи верните 5xx: Шляпс повторит доставку.
Приёмник Python
В SDK 0.5.0 есть готовый WebhookRequestHandler на aiohttp с проверкой секрета, передачей ошибок и ограниченным кешем повторов. Пример и ограничения кеша.
Пример на PHP
Пример принимает события одного бота и сохраняет их в SQLite с защитой от повторной записи. Нужен PHP с PDO SQLite. Настройте HTTPS на порту 443 и направьте URL вебхука на этот файл.
Задайте KODARI_WEBHOOK_SECRET с тем же значением, которое передали в setWebhook. В KODARI_WEBHOOK_DB укажите доступный PHP путь к SQLite вне публичного каталога сайта, например /var/lib/shlyaps-bot/inbox.sqlite.
<?php
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
http_response_code(405);
exit;
}
$secret = getenv('KODARI_WEBHOOK_SECRET');
$database = getenv('KODARI_WEBHOOK_DB');
if (!$secret || !$database) {
http_response_code(503);
exit;
}
$receivedSecret = $_SERVER['HTTP_X_SHLYAPS_BOT_API_SECRET_TOKEN'] ?? '';
if (!hash_equals($secret, $receivedSecret)) {
http_response_code(403);
exit;
}
$raw = file_get_contents('php://input', false, null, 0, 2097153);
if ($raw === false || strlen($raw) > 2097152) {
http_response_code(413);
exit;
}
$update = json_decode($raw, true);
if (!is_array($update) || !is_int($update['update_id'] ?? null)) {
http_response_code(400);
exit;
}
try {
$pdo = new PDO('sqlite:' . $database, null, null, [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);
$pdo->exec('CREATE TABLE IF NOT EXISTS updates (
update_id INTEGER PRIMARY KEY,
payload TEXT NOT NULL,
received_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
processed INTEGER NOT NULL DEFAULT 0
)');
$pdo->prepare('INSERT OR IGNORE INTO updates (update_id, payload) VALUES (?, ?)')
->execute([$update['update_id'], $raw]);
} catch (Throwable $error) {
http_response_code(503);
exit;
}
http_response_code(204);
Отдельный процесс должен читать записи с processed = 0, выполнять действия бота и отмечать обработанные записи. Учитывайте повторы и в этих действиях. Сам пример только сохраняет входящие события.
Когда события не приходят
Проверьте getWebhookInfo. Рост pending_update_count вместе с HTTP 404 обычно означает неправильный путь, HTTP 401 или HTTP 403 требует проверки секрета и правил доступа, HTTP 503 означает, что получатель временно не готов. Transport error N содержит код ошибки cURL.
Убедитесь, что адрес доступен по IPv4, сертификат доверенный и сервер не перенаправляет запрос на другой URL. Разрешите оба IP фронтов, указанных в подключении. Система повторно проверяет DNS перед каждой доставкой и не обращается к локальным адресам.
При недоступности фронтов доставка ждёт в очереди. Для повторной немедленной попытки после исправления получателя можно снова вызвать setWebhook; передайте секрет повторно и оставьте drop_pending_updates: false.