Updates

Webhooks

В режиме webhook Telegram отправляет каждый Update POST-запросом на ваш HTTPS endpoint. Это основной production-вариант.

Требования

  • публичный HTTPS (валидный сертификат);
  • быстрый ответ 200 OK (тяжёлую работу — в очередь);
  • проверка подлинности запроса.

Установка webhook

Лучше POST JSON, а не query string — иначе secret_token попадёт в shell history и access-логи прокси.

telegramApi($token, 'setWebhook', [
    'url'          => 'https://example.com/telegram/webhook',
    'secret_token' => $secret, // 1–256 символов A-Z, a-z, 0-9, _, -
    'allowed_updates' => ['message', 'callback_query'],
]);

Telegram будет присылать заголовок X-Telegram-Bot-Api-Secret-Token. Сверяйте его через hash_equals.

$header = $_SERVER['HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN'] ?? '';
if (!hash_equals($secret, $header)) {
    http_response_code(401);
    exit;
}
$raw = file_get_contents('php://input');
$update = json_decode((string) $raw, true);
if (!is_array($update)) {
    http_response_code(400);
    exit;
}
// TODO: сохранить update_id, поставить Job, вернуть 200
http_response_code(200);
echo 'ok';

Повторные доставки

Telegram может прислать один и тот же Update повторно. Храните обработанные update_id (UNIQUE) и пропускайте дубликаты. «Один cursor» на процесс не спасает при нескольких инстансах приложения.

Проверка

telegramApi($token, 'getWebhookInfo');

Связанные главы: getUpdates, PHP-клиент, проект заявка с сайта.