Como configurar o webhook de um bot do Telegram

Com um webhook, o Telegram envia cada atualização para o seu endpoint HTTPS em vez de você consultar getUpdates. Veja como configurá-lo corretamente e com segurança.

Faça em poucos cliques — sem código, sem servidor, direto no navegador.

Abrir o gerenciador de webhook

Requisitos

Uma URL HTTPS pública. HTTP simples não é aceito.
Porta 443, 80, 88 ou 8443.
Um certificado TLS válido (TLS 1.2+). Um autoassinado só funciona se você enviar a chave pública.
Seu endpoint deve responder rápido com HTTP 2xx; caso contrário o Telegram tenta de novo e as atualizações se acumulam.

Configurar o webhook online

Abra o Telegram Bot Manager e cole o token do bot do @BotFather.
Na aba Webhook informe a URL do seu handler.
Clique em Gerar para criar um token secreto e salve-o na configuração do servidor.
Escolha allowed_updates se precisar só de alguns tipos (ou de chat_member / reações, desativados por padrão).
Clique em Configurar webhook. O bloco de status mostra o resultado na hora.

Parâmetros

Parâmetro	O que faz
`url`	Endpoint HTTPS que recebe as atualizações como requisições POST em JSON.
`secret_token`	1–256 caracteres `A-Z a-z 0-9 _ -`, enviado no cabeçalho `X-Telegram-Bot-Api-Secret-Token` de cada requisição.
`allowed_updates`	Tipos de atualização a receber. Lista vazia = tudo exceto chat_member, message_reaction, message_reaction_count.
`max_connections`	Conexões HTTPS simultâneas, 1–100 (padrão 40).
`ip_address`	IP fixo em vez da resolução DNS.
`certificate`	Chave pública de um certificado autoassinado.
`drop_pending_updates`	Descarta as atualizações que aguardam na fila.

O mesmo com curl

curl -X POST "https://api.telegram.org/bot$BOT_TOKEN/setWebhook" \
  --form-string "url=https://example.com/telegram/webhook" \
  --form-string "secret_token=$WEBHOOK_SECRET" \
  --form-string 'allowed_updates=["message","callback_query"]' \
  --form-string "max_connections=40"

Com certificado autoassinado:

curl -X POST "https://api.telegram.org/bot$BOT_TOKEN/setWebhook" \
  --form-string "url=https://203.0.113.10:8443/webhook" \
  -F "certificate=@public.pem"

Verifique o token secreto no servidor

Sempre compare o cabeçalho com o seu segredo e rejeite as outras requisições — a URL do webhook sozinha não é um segredo.

// Node.js (Express): reject requests without the right secret
app.post('/telegram/webhook', (req, res) => {
  if (req.get('X-Telegram-Bot-Api-Secret-Token') !== process.env.WEBHOOK_SECRET) {
    return res.sendStatus(401);
  }
  // handle req.body (Update) ...
  res.sendStatus(200);
});

Erros comuns

Bad Request: bad webhook: An HTTPS URL must be provided for webhook — use https://.
Bad Request: bad webhook: Webhook can be set up only on ports 80, 88, 443 or 8443 — troque a porta ou coloque um proxy reverso na frente.
Bad Request: bad webhook: Failed to resolve host — o domínio não tem registro DNS público.
Bad Request: secret token contains unallowed characters — use apenas letras, dígitos, _ e -.