Verificador de webhook de bot do Telegram
Verifique o webhook do seu bot do Telegram com um clique: a ferramenta chama getWebhookInfo, mostra a URL, as atualizações pendentes e o último erro de entrega com uma dica de como corrigi-lo, e permite configurar ou apagar o webhook.
O token fica no seu navegador (localStorage) e é enviado apenas para api.telegram.org.
Configurar ou alterar o webhook
Como verificar o webhook de um bot do Telegram
- Cole o token do bot. Marque Servidor de testes se o bot estiver no ambiente de testes.
- Clique em Verificar webhook. Você recebe um de três resultados: nenhum webhook (o bot usa
getUpdates), um webhook sem erros nas últimas 24 horas ou um problema de entrega com a hora e o texto do último erro, além de uma dica. - Confira o contador de atualizações pendentes. Acima de 100 ele fica destacado: as atualizações estão se acumulando porque o seu servidor não as aceita.
- Abaixo aparece a resposta completa do
getWebhookInfo:url,has_custom_certificate,pending_update_count,last_error_date,last_error_message,max_connectionse outros campos. - Para alterar, abra Configurar ou alterar o webhook: informe uma URL HTTPS e um
secret_tokenopcional, escolha se quer descartar as atualizações pendentes e clique em setWebhook ou deleteWebhook. A verificação roda de novo automaticamente.
Erros comuns de webhook
A dica é escolhida a partir do texto de last_error_message:
| O erro se parece com | O que verificar |
|---|---|
| SSL / certificate | Um certificado válido para o domínio (ou um autoassinado enviado pelo parâmetro certificate do setWebhook), TLS 1.2+. |
| Wrong response from the webhook: 4xx/5xx | O caminho, a verificação do seu secret_token e os erros do servidor — o Telegram espera 2xx. |
| Timeout / connection reset | O servidor precisa ser acessível pela internet na porta 443, 80, 88 ou 8443 e responder rápido. |
| Connection refused | Nada escuta na porta, ou um firewall bloqueia o Telegram. |
| Host can't be resolved | Os registros DNS do domínio do webhook. |
O formulário envia apenas url, secret_token e drop_pending_updates. O segredo (1–256 caracteres A-Z a-z 0-9 _ -) chega no cabeçalho X-Telegram-Bot-Api-Secret-Token de cada requisição. Para allowed_updates, max_connections ou um certificado, use o /pt/telegram-bot-api-tester.html#setWebhook.
Privacidade
O token fica no localStorage do seu navegador, e getWebhookInfo, setWebhook e deleteWebhook são enviados direto para api.telegram.org — nada passa pelo nosso servidor. A mesma chamada está disponível no /pt/telegram-bot-api-tester.html#getWebhookInfo. Um passo a passo completo de configuração está em /pt/guides/telegram-bot-webhook.html, e o 409 Conflict e outros erros são explicados em /pt/guides/telegram-bot-api-errors.html.
Perguntas frequentes
Como saber se o meu bot do Telegram tem webhook?
Chame getWebhookInfo. Se url estiver vazia, não há webhook configurado e o bot funciona com getUpdates. O verificador acima faz essa chamada por você e explica o resultado.
Como apagar o webhook de um bot do Telegram?
Chame deleteWebhook — na ferramenta, abra Configurar ou alterar o webhook e clique em deleteWebhook. Marque Descartar atualizações pendentes apenas se quiser descartar as atualizações na fila. Depois disso, o getUpdates volta a funcionar.
Por que o pending_update_count não para de crescer?
O Telegram não consegue entregar as atualizações: o seu servidor está inacessível, lento ou responde com um status fora de 2xx. Veja o last_error_message; o Telegram continua tentando, e as atualizações ficam guardadas por até 24 horas.
O que significa "Wrong response from the webhook"?
O seu servidor respondeu com um status HTTP diferente de 2xx, por exemplo 404 por um caminho errado ou 500 por uma falha. O Telegram espera uma resposta 2xx rápida e, caso contrário, tenta de novo.
Outros utilitários
Localizador de chat IDEscape de MarkdownV2 e HTMLValidador de initData do Mini AppBot API Tester