Um novo guia centrado em Laravel mostra aos desenvolvedores como evitar que bots do Telegram sofram timeout, dupliquem ações ou travem sob carga, protegendo o webhook, usando Redis para idempotência e enviando tarefas pesadas para filas.

Por que os webhooks do Telegram precisam de mais do que uma simples rota

O Telegram envia cada interação do usuário para um bot como um HTTP POST para uma URL especificada pelo desenvolvedor. A plataforma espera um 200 OK em poucos segundos; qualquer demora maior fará com que ela tente novamente a requisição. As tentativas de reenvio significam que o mesmo update_id pode chegar várias vezes e, se o bot escrever em um banco de dados ou chamar APIs externas dentro da requisição, isso pode criar linhas duplicadas, mensagens duplas ou condições de corrida. Para bots que lidam com dezenas ou centenas de mensagens por segundo, essa latência torna-se rapidamente um impedimento.

1. Proteja o endpoint com um header secreto

O Telegram adiciona um header X-Telegram-Bot-Api-Secret-Token a cada chamada de webhook. Compare esse header com um segredo armazenado no servidor — usando a função hash_equals do PHP para evitar ataques de tempo — e rejeite qualquer requisição que não se origine do Telegram. No Laravel, coloque essa verificação em um middleware para que a validação ocorra antes que o controller processe o payload.

2. Torne cada atualização idempotente com Redis

Cada payload recebido carrega um update_id único. O guia sugere gravar esse ID no Redis com a flag NX (set-if-not-exists). A operação tem sucesso apenas na primeira ocorrência; uma tentativa de reenvio encontrará a chave já presente e o webhook poderá retornar imediatamente 200 OK, sinalizando ao Telegram que a atualização foi processada. Como o Redis reside na memória, a verificação adiciona virtualmente nenhuma latência, e a chave permanece para detectar duplicatas.

3. Delegue o trabalho pesado para jobs em segundo plano

Mesmo com uma verificação rápida no Redis, a lógica de negócio do bot — gravações no banco de dados, chamadas de APIs de terceiros, composição de mensagens — nunca deve ser executada dentro da requisição do webhook. Despache um job enfileirado do Laravel assim que o webhook for verificado e o update_id for armazenado. Envie a resposta HTTP instantaneamente, permitindo que o worker processe o job no seu próprio ritmo. Isso mantém o bot dentro do prazo de resposta do Telegram e evita que a plataforma tente reenviar a requisição.

Ajustes para nível de produção

  • Respeite os limites de taxa. O Telegram retorna 429 Too Many Requests com um header Retry-After quando um bot excede seus limites por segundo. Os workers da fila devem ler esse header e pausar antes de tentar novamente o job que falhou.
  • Persista antes de responder. Grave qualquer dado do usuário no banco de dados primeiro; somente após um commit bem-sucedido o bot deve enviar uma mensagem de confirmação. Essa ordem evita cenários onde uma mensagem chega ao usuário, mas o registro correspondente nunca é materializado.
  • Reduza o tamanho dos payloads de callback. O Telegram limita o callback_data a 64 bytes. Armazene blobs maiores no banco de dados e passe apenas um ID de referência no payload do botão para permanecer dentro do limite.

Resumo: Autenticar a requisição, remover duplicatas com Redis e delegar o trabalho para filas permite que desenvolvedores Laravel construam bots do Telegram que respondem instantaneamente, respeitam os limites de taxa e escalam de forma limpa conforme a demanda dos usuários aumenta.