Build a Lightweight Telegram Webhook Handler in Laravel with Queues and Feature Tests

// config/services.php
return [
    // ... other services
    'telegram' => [
        'bot_token' => env('TELEGRAM_BOT_TOKEN'),
        'webhook_secret' => env('TELEGRAM_WEBHOOK_SECRET'),
    ],
];

TELEGRAM_BOT_TOKEN=123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ
TELEGRAM_WEBHOOK_SECRET=a_secure_random_string_here

namespace App\Services;

use Illuminate\Support\Facades\Http;
use Illuminate\Http\Client\Response;
use RuntimeException;

class TelegramClient

{
    protected string $baseUrl;

    public function __construct()
    {
        $token = config('services.telegram.bot_token');
        if (!$token) {
            throw new RuntimeException('Telegram Bot Token is not configured.');
        }
        $this->baseUrl = "https://api.telegram.org/bot{$token}/";
    }

    public function sendMessage(array $params): Response
    {
        return Http::timeout(10)
            ->post($this->baseUrl . 'sendMessage', $params);
    }
}

namespace App\Http\Controllers;

use App\Jobs\ProcessTelegramUpdateJob;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

class TelegramWebhookController extends Controller
{
    public function __invoke(Request $request): Response
    {
        $expectedSecret = config('services.telegram.webhook_secret');
        $providedSecret = $request->header('X-Telegram-Bot-Api-Secret-Token');

        if (!$expectedSecret || $providedSecret !== $expectedSecret) {
            return response('Unauthorized', 401);
        }

        $update = $request->all();
        if (!isset($update['update_id'])) {
            return response('Invalid payload', 400);
        }

        // Dispatch to queue to process asynchronously and respond 200 OK immediately
        ProcessTelegramUpdateJob::dispatch($update);

        return response('OK', 200);
    }
}

use App\Http\Controllers\TelegramWebhookController;
use Illuminate\Support\Facades\Route;

Route::post('/telegram/webhook', TelegramWebhookController::class);

namespace App\Jobs;

use App\Services\TelegramClient;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

class ProcessTelegramUpdateJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(public array $update) {}

    public function handle(TelegramClient $telegram): void
    {
        $message = $this->update['message'] ?? null;
        if (!$message || !isset($message['text'], $message['chat']['id'])) {
            return;
        }

        $chatId = $message['chat']['id'];
        $text = $message['text'];

        if ($text === '/start') {
            // Always escape dynamic user input using htmlspecialchars when using HTML parse_mode
            $welcomeText = "Hello! Welcome to our bot.";

            $telegram->sendMessage([
                'chat_id' => $chatId,
                'text' => $welcomeText,
                'parse_mode' => 'HTML',
            ]);
        }
    }
}

namespace Tests\Feature;

use App\Jobs\ProcessTelegramUpdateJob;
use App\Services\TelegramClient;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Queue;
use Tests\TestCase;

class TelegramWebhookTest extends TestCase
{
    protected function setUp(): void
    {
        parent::setUp();
        config([
            'services.telegram.bot_token' => 'test-token',
            'services.telegram.webhook_secret' => 'test-secret',
        ]);
    }

    public function test_webhook_dispatches_job_on_valid_secret(): void
    {
        Queue::fake();

        $response = $this->postJson('/api/telegram/webhook', [
            'update_id' => 12345,
            'message' => [
                'chat' => ['id' => 999],
                'text' => '/start',
            ],
        ], [
            'X-Telegram-Bot-Api-Secret-Token' => 'test-secret',
        ]);

        $response->assertStatus(200);
        Queue::assertDispatched(ProcessTelegramUpdateJob::class, function ($job) {
            return $job->update['update_id'] === 12345;
        });
    }

    public function test_webhook_rejects_invalid_secret(): void
    {
        Queue::fake();

        $response = $this->postJson('/api/telegram/webhook', [
            'update_id' => 12345,
        ], [
            'X-Telegram-Bot-Api-Secret-Token' => 'wrong-secret',
        ]);

        $response->assertStatus(401);
        Queue::assertNothingDispatched();
    }

    public function test_client_sends_correct_payload(): void
    {
        Http::fake([
            'api.telegram.org/*' => Http::response(['ok' => true, 'result' => []], 200),
        ]);

        $client = new TelegramClient();
        $response = $client->sendMessage([
            'chat_id' => 999,
            'text' => 'Test message',
        ]);

        $this->assertTrue($response->successful());
        Http::assertSent(function ($request) {
            return $request->url() === 'https://api.telegram.org/bottest-token/sendMessage'
                && $request['chat_id'] === 999
                && $request['text'] === 'Test message';
        });
    }
}