Una nuova guida incentrata su Laravel mostra agli sviluppatori come evitare che i bot di Telegram vadano in timeout, duplicino le azioni o vadano in crash sotto carico, proteggendo il webhook, utilizzando Redis per l'idempotenza e delegando i compiti più pesanti alle code.

Perché i webhook di Telegram richiedono più di una semplice rotta

Telegram invia ogni interazione dell'utente a un bot tramite una richiesta HTTP POST a un URL specificato dallo sviluppatore. La piattaforma si aspetta un 200 OK entro pochi secondi; se il tempo supera tale soglia, effettua un nuovo tentativo della richiesta. I tentativi di riproporre la richiesta significano che lo stesso update_id può arrivare più volte e, se il bot scrive su un database o chiama API esterne all'interno della richiesta, può creare righe duplicate, messaggi doppi o race condition. Per i bot che gestiscono decine o centinaia di messaggi al secondo, quella latenza diventa rapidamente un ostacolo.

1. Proteggi l'endpoint con un header segreto

Telegram aggiunge un header X-Telegram-Bot-Api-Secret-Token a ogni chiamata webhook. Confronta quell'header con un segreto memorizzato sul server — utilizzando la funzione hash_equals di PHP per evitare attacchi di tipo timing — e rifiuta qualsiasi richiesta che non provenga da Telegram. In Laravel, inserisci questo controllo in un middleware, in modo che la verifica venga eseguita prima che il controller acceda al payload.

2. Rendi ogni aggiornamento idempotente con Redis

Ogni payload in entrata contiene un update_id univoco. La guida suggerisce di scrivere quell'ID su Redis utilizzando il flag NX (set-if-not-exists). L'operazione ha successo solo alla prima occorrenza; un tentativo di riproporre la richiesta troverà la chiave già presente e il webhook potrà restituire immediatamente un 200 OK, segnalando a Telegram che l'aggiornamento è stato gestito. Poiché Redis risiede in memoria, il controllo non aggiunge praticamente alcuna latenza e la chiave rimane memorizzata per rilevare eventuali duplicati.

3. Delega i compiti pesanti ai job in background

Anche con un controllo Redis veloce, la logica di business del bot — scritture sul database, chiamate a API di terze parti, composizione dei messaggi — non dovrebbe mai essere eseguita all'interno della richiesta webhook. Invia un job in coda di Laravel non appena il webhook viene verificato e l' update_id memorizzato. Invia la risposta HTTP istantaneamente, lasciando che il worker elabori il job al proprio ritmo. Questo permette al bot di rientrare ampiamente nei tempi di risposta di Telegram ed evita che la piattaforma tenti nuovi invii.

Ottimizzazioni per la produzione

  • Rispettare i rate limit. Telegram restituisce un errore 429 Too Many Requests con un header Retry-After quando un bot supera i propri limiti al secondo. I worker della coda dovrebbero leggere quell'header e mettersi in pausa prima di riprovare il job fallito.
  • Persisti prima di rispondere. Scrivi prima i dati dell'utente nel database; solo dopo un commit andato a buon fine il bot dovrebbe inviare un messaggio di conferma. Questo ordine evita scenari in cui un messaggio raggiunge l'utente ma il record corrispondente non viene mai creato.
  • Riduci i payload dei callback. Telegram limita callback_data a 64 byte. Memorizza i blob più grandi nel database e passa solo un ID di riferimento nel payload del pulsante per rimanere entro il limite.

In sintesi: Autenticare la richiesta, eliminare i duplicati con Redis e delegare il lavoro alle code consente agli sviluppatori Laravel di costruire bot di Telegram che rispondono istantaneamente, rispettano i rate limit e scalano in modo pulito all'aumentare della domanda degli utenti.