Webhook de Telegram: cómo configurar setWebhook para tu bot (Python y n8n)

Actualizado: 29 de octubre de 2026 · 7 min de lectura

Un webhook hace que Telegram envíe cada actualización de tu bot, por POST y en JSON, a una URL HTTPS tuya en cuanto ocurre. Para configurar el webhook de un bot de Telegram llamas a setWebhook con esa URL (y, de preferencia, un secret_token), compruebas el estado con getWebhookInfo y respondes a cada petición con un código 2xx.

Webhook o getUpdates: cuál elegir

No puedes usar ambos a la vez: mientras haya un webhook activo, getUpdates responde 409 Conflict. Si todavía no tienes bot, empieza por cómo crear un bot en Telegram.

Requisitos del webhook

• URL HTTPS accesible desde internet; HTTP plano no se acepta.
• Puerto 443, 80, 88 u 8443. Si no es el 443, inclúyelo en la URL: https://bot.example.com:8443/webhook.
• Certificado válido cuyo CN o SAN coincida con el dominio, con la cadena completa (incluidos los intermedios) y TLS 1.2 o superior.
• Certificado autofirmado: sirve, pero debes subir su parte pública en el parámetro certificate.
• IPv4: los webhooks no admiten IPv6. Las peticiones llegan desde 149.154.160.0/20 y 91.108.4.0/22, por si filtras con un firewall.
• Sin redirecciones: la URL debe responder directamente.

Configurar el webhook con setWebhook

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

Si todo va bien, la respuesta es {"ok":true,"result":true,"description":"Webhook was set"}. Los parámetros:

• url: tu endpoint HTTPS. Una cadena vacía elimina el webhook.
• secret_token: de 1 a 256 caracteres (A-Z, a-z, 0-9, _ y -). Telegram lo envía en el encabezado X-Telegram-Bot-Api-Secret-Token de cada petición.
• allowed_updates: tipos de actualización que quieres recibir. Si no lo envías, se conserva la configuración anterior.
• drop_pending_updates: descarta las actualizaciones acumuladas.
• max_connections: conexiones simultáneas, de 1 a 100 (40 por defecto).
• certificate e ip_address: certificado autofirmado e IP fija a la que enviar, si los necesitas.

Con certificado autofirmado, la petición debe ser multipart/form-data:

curl -F "url=https://203.0.113.10:8443/webhook" \
  -F "certificate=@public.pem" \
  "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setWebhook"

También puedes registrar la URL desde el navegador con setWebhook en Bot API Tester.

Verificar el webhook con getWebhookInfo

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

{
  "ok": true,
  "result": {
    "url": "https://bot.example.com/telegram/webhook",
    "has_custom_certificate": false,
    "pending_update_count": 12,
    "last_error_date": 1793232000,
    "last_error_message": "Wrong response from the webhook: 500 Internal Server Error",
    "max_connections": 40,
    "allowed_updates": ["message", "callback_query"]
  }
}

Fíjate en pending_update_count (actualizaciones esperando entrega) y last_error_message (último error al entregar). Si el contador crece y hay un error reciente, Telegram no logra hablar con tu servidor. Si url está vacía, no hay webhook y el bot usa getUpdates.

Webhook de Telegram en Python: validar el secret_token

Este handler mínimo con Flask rechaza las peticiones sin tu secreto, contesta los mensajes de texto y responde 200:

import hmac
import os

import requests
from flask import Flask, abort, request

TOKEN = os.environ["TELEGRAM_BOT_TOKEN"]
SECRET = os.environ["TELEGRAM_WEBHOOK_SECRET"]
API = f"https://api.telegram.org/bot{TOKEN}"

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, SECRET):
        abort(403)
    update = request.get_json(silent=True) or {}
    message = update.get("message")
    if message and "text" in message:
        requests.post(f"{API}/sendMessage", timeout=10, json={
            "chat_id": message["chat"]["id"],
            "text": "Recibido: " + message["text"],
        })
    return "", 200

• Responde con 2xx lo antes posible. Si devuelves otro código o tardas demasiado, Telegram reintenta la entrega.
• Manda las tareas lentas (IA, archivos, APIs externas) a una cola o a segundo plano.
• Usa update_id para descartar duplicados cuando llegue un reintento.

Para dar formato a las respuestas o añadir botones, consulta cómo enviar mensajes con la API.

Volver a getUpdates con deleteWebhook

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

Devuelve "result": true y, desde ese momento, getUpdates vuelve a funcionar. Quita drop_pending_updates si quieres conservar las actualizaciones pendientes.

Errores frecuentes

• Error que contiene An HTTPS URL must be provided for webhook: pasaste una URL http:// o sin esquema. Usa HTTPS.
• Webhook can be set up only on ports 80, 88, 443 or 8443: cambia el puerto.
• 409 Conflict: can't use getUpdates method while webhook is active: elimina el webhook con deleteWebhook o deja de llamar a getUpdates.
• Tu handler responde 403: el secreto de tu servidor no coincide con el secret_token registrado. Vuelve a llamar a setWebhook con el valor correcto.
• Errores SSL en last_error_message: falta un certificado intermedio o el dominio no coincide con el certificado.

Webhook de Telegram en n8n: por qué falla en localhost

El disparador de Telegram de n8n funciona con webhook: al activar el flujo, n8n registra su propia URL con setWebhook. Si n8n corre en tu computadora con http://localhost, Telegram no puede alcanzarlo (no es público ni HTTPS) y el registro falla con el error de HTTPS de arriba. Publica n8n en un dominio con HTTPS, por ejemplo detrás de un proxy inverso o con un túnel, y asegúrate de que la URL registrada sea la pública. Luego confirma con getWebhookInfo que url apunta a tu instancia.

Recuerda que, mientras ese flujo esté activo, cualquier script que llame a getUpdates con el mismo token recibirá 409. Si solo necesitas el chat id, sigue la guía cómo obtener el chat id.