Set Up a Secure and Idempotent Telegram Webhook in Pure PHP

<?php
// register.php

$botToken = getenv('TELEGRAM_BOT_TOKEN');
$webhookUrl = 'https://yourdomain.com/webhook.php';
$secretToken = getenv('TELEGRAM_SECRET_TOKEN'); // A secure random string (1-256 characters)

if (!$botToken || !$secretToken) {
    die("Missing environment variables: TELEGRAM_BOT_TOKEN or TELEGRAM_SECRET_TOKEN.\n");
}

$url = "https://api.telegram.org/bot{$botToken}/setWebhook";
$payload = [
    'url' => $webhookUrl,
    'secret_token' => $secretToken,
    'allowed_updates' => ['message', 'callback_query']
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);
$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if (curl_errno($ch)) {
    die('cURL Error: ' . curl_error($ch) . "\n");
}
curl_close($ch);

if ($httpStatus !== 200) {
    die("HTTP Error {$httpStatus}: {$response}\n");
}

$result = json_decode($response, true);
if (json_last_error() !== JSON_ERROR_NONE) {
    die("Failed to parse JSON response.\n");
}

if (!($result['ok'] ?? false)) {
    die("Telegram API Error: " . ($result['description'] ?? 'Unknown error') . "\n");
}

echo "Webhook successfully registered.\n";

CREATE TABLE `telegram_processed_updates` (
    `update_id` BIGINT UNSIGNED NOT NULL,
    `processed_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (`update_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

<?php
// webhook.php

// 1. Send fast HTTP 200 OK response
// This releases the connection immediately if PHP-FPM is used.
ob_start();
echo json_encode(['status' => 'ok']);
header('Connection: close');
header('Content-Length: ' . ob_get_length());
header('Content-Type: application/json');
ob_end_flush();
flush();

if (function_exists('fastcgi_finish_request')) {
    fastcgi_finish_request();
}

// 2. Validate Secret Token
$headers = getallheaders();
$receivedToken = $headers['X-Telegram-Bot-Api-Secret-Token'] ?? '';
$expectedToken = getenv('TELEGRAM_SECRET_TOKEN');

if (empty($expectedToken) || !hash_equals($expectedToken, $receivedToken)) {
    http_response_code(403);
    exit('Unauthorized');
}

// 3. Read and parse payload
$rawInput = file_get_contents('php://input');
$update = json_decode($rawInput, true);

if (json_last_error() !== JSON_ERROR_NONE || !isset($update['update_id'])) {
    http_response_code(400);
    exit('Invalid JSON');
}

$updateId = (int)$update['update_id'];

// 4. Enforce Idempotency via Database
$dsn = "mysql:host=" . getenv('DB_HOST') . ";dbname=" . getenv('DB_NAME') . ";charset=utf8mb4";
try {
    $pdo = new PDO($dsn, getenv('DB_USER'), getenv('DB_PASS'), [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
    ]);

    // Attempt to insert the update_id
    $stmt = $pdo->prepare("INSERT INTO telegram_processed_updates (update_id) VALUES (:update_id)");
    $stmt->execute([':update_id' => $updateId]);
} catch (PDOException $e) {
    // SQLSTATE 23000 indicates a duplicate key violation (update already processed)
    if ($e->getCode() == 23000) {
        exit('Duplicate update');
    }
    error_log("Database error: " . $e->getMessage());
    exit;
}

// 5. Process the update safely
if (isset($update['message'])) {
    $message = $update['message'];
    $chatId = $message['chat']['id'] ?? null;
    $text = $message['text'] ?? '';

    if ($chatId && $text === '/start') {
        sendTelegramMessage($chatId, "Hello! Your update ID <b>" . htmlspecialchars((string)$updateId, ENT_QUOTES, 'UTF-8') . "</b> was processed securely.");
    }
}

function sendTelegramMessage($chatId, $text) {
    $botToken = getenv('TELEGRAM_BOT_TOKEN');
    $url = "https://api.telegram.org/bot{$botToken}/sendMessage";
    $payload = [
        'chat_id' => $chatId,
        'text' => $text,
        'parse_mode' => 'HTML'
    ];

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 5);

    $response = curl_exec($ch);
    $httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    if (!curl_errno($ch) && $httpStatus === 200) {
        $result = json_decode($response, true);
        if (json_last_error() === JSON_ERROR_NONE && !($result['ok'] ?? false)) {
            error_log("Telegram API Error: " . ($result['description'] ?? 'Unknown error'));
        }
    }
    curl_close($ch);
}