🌙

Доставка и пример обработчика

Шляпс отправляет один 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.

13 просмотров