Como configurar o webhook do bot do Telegram: setWebhook, secret_token e n8n

Atualizado em: 29 de outubro de 2026 · 7 min de leitura

Um webhook faz o Telegram enviar cada update do seu bot por HTTPS POST para uma URL sua, em vez de você ficar chamando getUpdates. Para configurar o webhook do Telegram bot, chame setWebhook com uma URL HTTPS pública (portas 443, 80, 88 ou 8443) e um secret_token, depois confira o status com getWebhookInfo. Este guia mostra os comandos, o código do handler e os erros mais comuns — inclusive no n8n.

Webhook ou getUpdates?

Os dois modos são mutuamente exclusivos: enquanto houver webhook, getUpdates responde 409 Conflict. Em ambos os casos os updates pendentes ficam guardados por no máximo 24 horas.

Requisitos do webhook

• URL HTTPS pública, mesmo na porta 80 — HTTP puro não é aceito. TLS 1.2 ou superior.
• Portas suportadas: 443, 80, 88 e 8443.
• Certificado válido, com CN ou SAN igual ao domínio e cadeia completa (inclua o certificado intermediário). Certificado autoassinado também serve, desde que você envie a parte pública no parâmetro certificate (upload multipart/form-data, formato PEM).
• IPv4 (IPv6 não é suportado para webhooks) e nada de redirecionamentos.
• Firewall liberado para as redes do Telegram: 149.154.160.0/20 e 91.108.4.0/22.

Como configurar o webhook com setWebhook

Primeiro gere um segredo (a saída hexadecimal só usa caracteres permitidos):

openssl rand -hex 32

Depois registre a URL:

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://bot.seudominio.com.br/telegram/webhook",
    "secret_token": "COLE_AQUI_O_SEGREDO",
    "allowed_updates": ["message", "callback_query"],
    "drop_pending_updates": true,
    "max_connections": 40
  }'

Resposta esperada: {"ok":true,"result":true,"description":"Webhook was set"}. O que cada parâmetro faz:

• url — endereço HTTPS que recebe os updates; string vazia remove o webhook.
• secret_token — 1 a 256 caracteres (A-Z a-z 0-9 _ -), enviado no header X-Telegram-Bot-Api-Secret-Token.
• allowed_updates — tipos de update desejados. Se omitido, vale a configuração anterior.
• drop_pending_updates — descarta os updates acumulados.
• max_connections — conexões simultâneas, de 1 a 100 (padrão 40).
• certificate e ip_address — certificado autoassinado e IP fixo, se precisar.

Prefere um formulário? Use o Bot API Tester no setWebhook e confira o resultado em getWebhookInfo.

Verificar com getWebhookInfo

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/getWebhookInfo"

{
  "ok": true,
  "result": {
    "url": "https://bot.seudominio.com.br/telegram/webhook",
    "has_custom_certificate": false,
    "pending_update_count": 12,
    "last_error_date": 1793280000,
    "last_error_message": "Wrong response from the webhook: 404 Not Found",
    "max_connections": 40,
    "allowed_updates": ["message", "callback_query"]
  }
}

Se pending_update_count só cresce, o Telegram não está conseguindo entregar. O last_error_message diz o motivo (resposta HTTP do seu servidor, timeout, erro de SSL) e o last_error_date diz quando, em Unix time.

Validar o header X-Telegram-Bot-Api-Secret-Token

Qualquer pessoa pode fazer POST na sua URL; o header com o segredo prova que a requisição veio do webhook que você configurou. Exemplo com Flask:

import hmac
import os

from flask import Flask, abort, request

SECRET = os.environ["WEBHOOK_SECRET"]
app = Flask(__name__)

@app.post("/telegram/webhook")
def telegram_webhook():
    received = request.headers.get("X-Telegram-Bot-Api-Secret-Token", "")
    if not hmac.compare_digest(received.encode(), SECRET.encode()):
        abort(403)
    update = request.get_json(silent=True) or {}
    msg = update.get("message")
    if msg and "text" in msg:
        # resposta direta: o Telegram executa este sendMessage
        return {"method": "sendMessage", "chat_id": msg["chat"]["id"], "text": "Recebido!"}
    return "", 200

Responda rápido com status 2xx. Qualquer outro status faz o Telegram repetir a entrega, e você recebe o mesmo update de novo — use o update_id para ignorar duplicados. Trabalho pesado (IA, banco, APIs externas) vai para uma fila. Responder com JSON contendo method economiza uma requisição, mas você não fica sabendo se ela deu certo; para isso, chame a API normalmente, como no guia enviar mensagens pela API do Telegram.

Remover o webhook e voltar ao getUpdates

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/deleteWebhook?drop_pending_updates=true"

Sem drop_pending_updates, os updates pendentes continuam na fila e chegam no próximo getUpdates.

Erros comuns

• Bad Request: bad webhook: An HTTPS URL must be provided for webhook: a URL começa com http://. Use HTTPS.
• 409 Conflict no getUpdates: há um webhook ativo. Chame deleteWebhook se quiser voltar ao polling.
• n8n em localhost sem HTTPS: o Telegram não alcança localhost nem aceita HTTP. Publique a instância num domínio com HTTPS ou use um túnel HTTPS. E não divida o mesmo bot entre o gatilho do n8n e um script com polling.
• Webhook “sumiu” ou mudou: cada bot tem um único webhook, e cada setWebhook substitui o anterior. Outra integração com o mesmo token pode ter trocado a URL. Se suspeitar de vazamento, siga o guia telegram bot token e revogue o token.
• 403 no seu próprio log: o segredo do servidor não bate com o do setWebhook. Registre o webhook de novo com o mesmo valor.
• Erro de SSL no last_error_message: confira a cadeia do certificado (intermediário incluído) e se o domínio bate com o CN/SAN.

Começando do zero? Veja antes como criar um bot no Telegram.