Secure and Queue Telegram Webhooks in Laravel with Redis Idempotency

iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more

Use Telegram’s webhook as a short, authenticated intake endpoint: verify the configured secret header, validate the update, atomically claim its update_id in shared Redis, then queue the work. Make the job’s business effects safe to repeat as well. These controls reduce duplicate work and limit concurrent execution; they do not provide exactly-once processing.

How the request should flow

1. Telegram delivers an update to your publicly reachable HTTPS webhook URL.
2. Laravel checks the secret header before accepting the request for processing.
3. The application validates the update and atomically claims its identity in Redis.
4. A queued job processes accepted work outside the webhook request, with retries and independently repeat-safe side effects.
5. The endpoint acknowledges the request once the application has safely accepted it for processing.

Telegram retains pending updates for no longer than 24 hours, according to its Bot API documentation. That is not a guarantee that your application will process an update exactly once—or that a failed handoff between your endpoint and queue will recover automatically.

#	Preview	Product	Price
1		Corning Cable DS-67329650-01 ITM-BRKT-L-MNT-5 Redi-Rail L-Shaped Bracket	$32.50	Buy on Amazon

Choose webhooks or polling

Telegram offers two ways to receive updates: webhooks, where Telegram pushes updates to your server, and getUpdates, where your application polls Telegram. They are mutually exclusive for a bot; do not run polling while its webhook is active. Updates contain an update_id, which is useful for recognizing repeats and restoring order when updates arrive out of sequence. After a week without new updates, Telegram may choose the next identifier randomly rather than sequentially, so do not treat it as a permanent timestamp or global sequence.

Prepare a reachable HTTPS endpoint

Telegram requires TLS and a publicly reachable webhook endpoint. Its webhook documentation lists ports 443, 80, 88, and 8443 as supported. Configure Telegram with the final endpoint URL: Telegram’s FAQ says webhook redirects are unsupported. Check the current webhook guide and FAQ against your deployment’s network and TLS setup.

#1 Best Overall

Corning Cable DS-67329650-01 ITM-BRKT-L-MNT-5 Redi-Rail L-Shaped Bracket

• Redi-Rail
• Bracket
• L-Shaped

$32.50

Buy on Amazon

When registering the webhook with setWebhook, provide the final HTTPS URL and a high-entropy secret_token. Store the bot token and webhook secret in deployment-managed configuration, not source control. Avoid putting them in logs or client-visible error messages. Telegram specifically advises developers to keep the bot token in a secure place and share it only with people who need direct access, in its developer introduction.

Telegram’s FAQ also suggests using a secret path as an origin-checking aid. A hard-to-guess URL path can add defense in depth, but it is not a replacement for checking Telegram’s secret-token header.

Authenticate before accepting an update

Telegram sends the configured webhook secret in the X-Telegram-Bot-Api-Secret-Token header. Compare it with the expected value on every request, before validating or dispatching the update. Return a generic rejection for a missing or incorrect header; never echo either secret in the response.

For example, define the webhook secret and a non-secret idempotency namespace in Laravel’s service configuration, with values supplied by your environment:

'telegram' => [
    'webhook_secret' => env('TELEGRAM_WEBHOOK_SECRET'),
    'idempotency_namespace' => env('TELEGRAM_IDEMPOTENCY_NAMESPACE'),
    'idempotency_ttl' => (int) env('TELEGRAM_IDEMPOTENCY_TTL'),
],

Set an explicit idempotency retention value appropriate to your replay and recovery window; do not rely on an unset or guessed default. Keep the namespace stable for the bot, and do not use the bot token as part of a Redis key.

Claim each update atomically, then queue it

Laravel’s Redis cache store can perform an atomic add: it creates the key only if that key does not already exist. Use the same central Redis-backed cache for all web instances and workers, so concurrent requests share the claim. A local in-memory cache cannot coordinate separate processes.

This controller sketch shows the sequence. It assumes the Redis cache store is configured and available under the redis name, and that the three Telegram configuration values above are set.

use AppJobsProcessTelegramUpdate;
use IlluminateHttpRequest;
use IlluminateSupportFacadesCache;
use IlluminateSupportFacadesRoute;

Route::post('/webhooks/telegram', function (Request $request) {
    $expected = (string) config('services.telegram.webhook_secret');
    $provided = (string) $request->header('X-Telegram-Bot-Api-Secret-Token', '');

    if ($expected === '' || ! hash_equals($expected, $provided)) {
        return response('', 403);
    }

    $validated = $request->validate([
        'update_id' => ['required', 'integer', 'min:0'],
    ]);

    $namespace = (string) config('services.telegram.idempotency_namespace');
    $ttl = (int) config('services.telegram.idempotency_ttl');

    if ($namespace === '' || $ttl < 1) {
        return response('', 500);
    }

    $updateId = (string) $validated['update_id'];
    $key = "telegram:update:{$namespace}:{$updateId}";
    $claimed = Cache::store('redis')->add($key, 'claimed', $ttl);

    if (! $claimed) {
        return response('', 200);
    }

    ProcessTelegramUpdate::dispatch($request->all());

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

In production, put authentication in dedicated route middleware if that makes the boundary easier to audit, and validate the fields your bot actually handles—not only update_id. Apply request-size limits appropriate to the endpoint. Pass only validated data to the job, or pass a durable reference if the full update is stored elsewhere.

The duplicate branch returns success without dispatching a second job: Telegram’s repeated delivery has already been accepted under that update identity. The key combines a bot namespace and update_id, avoiding collisions if one Redis instance serves multiple bots. Keep the key’s retention long enough for the application’s realistic replay and recovery needs; there is no universal TTL.

Account for the claim-to-dispatch failure window

The cache claim and queue dispatch are separate operations. If the process stops after creating the key but before dispatching the job, a later delivery will see the existing key and be acknowledged as a duplicate, although no job was queued. Simply deleting the key after a dispatch error is not always safe either: an error can leave uncertainty about whether the queue accepted the job, and clearing the claim could permit duplicate effects.

If losing work in this window is unacceptable, use a durable handoff such as a transactional outbox or a recoverable state machine. Record the update and its processing state durably, then have a worker publish or process pending records and mark them complete. Design the recovery path to tolerate the queue receiving the same work more than once.

Make the job and its effects repeat-safe

Redis request deduplication prevents two deliveries from independently claiming the same update while the claim remains. It cannot stop a job from running again after a timeout, retry, worker crash, or ambiguous external response. The job should therefore make side effects independently idempotent where possible—for example, use a stable update identity when recording a business operation, or check durable state before applying it again.

Laravel’s queue controls address different points in the flow:

Laravel documents ShouldBeUnique for suppressing dispatch while a lock based on uniqueId is held. uniqueFor can bound the lock lifetime, and uniqueVia can select a cache repository. Laravel also documents ShouldBeUniqueUntilProcessing, which releases uniqueness just before processing; ordinary ShouldBeUnique holds it through completion or exhaustion of retries. Unique constraints do not apply to jobs inside batches. Consult the Laravel 12 queue documentation and match guidance to the Laravel version actually installed.

Use a uniqueness key derived from the update identity if preventing duplicate job dispatch is useful, but keep the Redis claim and job-side idempotency: they protect different boundaries. Choose WithoutOverlapping when the concern is simultaneous processing, and configure lock expiry so a worker that terminates abnormally does not block work indefinitely.

Coordinate retries, timeouts, and recovery

Configure the queue connection’s Redis retry_after, the worker timeout, job attempts, backoff, lock expiry, and idempotency retention as one policy. The timeout and retry_after must be coordinated so a job is not made available for another worker while the first worker is still expected to run. The right values depend on job duration, external service behavior, and the acceptable recovery window; no single setting is safe for every bot.

Laravel attempts can be consumed by exceptions, manual releases, middleware releases, timeouts, or normal completion. Monitor failed jobs and queue health, inspect failures, and use Laravel’s failed-job recovery tooling where appropriate. A retry is another execution attempt, not proof that an earlier attempt had no effect. Check the queue documentation for the installed Laravel version when configuring retries, timeouts, and recovery.

Quick Recap

Bestseller No. 1

Corning Cable DS-67329650-01 ITM-BRKT-L-MNT-5 Redi-Rail L-Shaped Bracket

Redi-Rail; Bracket; L-Shaped

$32.50

Deployment checklist

• Use one receive mode for the bot: webhook or getUpdates polling.
• Serve Telegram’s configured final webhook URL over public HTTPS on a supported port, without redirects.
• Register a high-entropy secret_token; compare its header on every request before accepting work.
• Keep bot credentials and webhook secrets out of source control, logs, and client-visible responses.
• Validate payload size and the fields the bot handles before claiming an update.
• Use an atomic Redis claim with a stable, bot-specific namespace shared by all web and worker processes.
• Choose claim retention, lock expiry, attempts, backoff, timeout, and retry_after for the workload and recovery plan.
• Use a durable handoff if the claim-to-dispatch gap must not risk lost work, and make business side effects safe to repeat.
• Monitor failed jobs and test recovery behavior, including repeated deliveries and worker termination.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.