Cómo configurar el webhook de un bot de Telegram

Con un webhook, Telegram envía cada actualización a tu endpoint HTTPS en lugar de que tengas que consultar getUpdates. Así se configura de forma correcta y segura.

Hazlo en unos clics: sin código, sin servidor, directamente en el navegador.

Abrir el gestor de webhooks

Requisitos

Una URL HTTPS pública. HTTP simple no se acepta.
Puerto 443, 80, 88 u 8443.
Un certificado TLS válido (TLS 1.2+). Uno autofirmado solo funciona si subes su clave pública.
Tu endpoint debe responder rápido con HTTP 2xx; si no, Telegram reintenta y las actualizaciones se acumulan.

Configurar el webhook en línea

Abre Telegram Bot Manager y pega el token del bot de @BotFather.
En la pestaña Webhook introduce la URL de tu manejador.
Pulsa Generar para crear un token secreto y guárdalo en la configuración del servidor.
Elige allowed_updates si solo necesitas algunos tipos (o chat_member / reacciones, desactivados por defecto).
Pulsa Configurar webhook. El bloque de estado muestra el resultado al instante.

Parámetros

Parámetro	Qué hace
`url`	Endpoint HTTPS que recibe las actualizaciones como solicitudes POST en JSON.
`secret_token`	1–256 caracteres `A-Z a-z 0-9 _ -`, enviado en el encabezado `X-Telegram-Bot-Api-Secret-Token` de cada solicitud.
`allowed_updates`	Tipos de actualización a recibir. Lista vacía = todo excepto chat_member, message_reaction, message_reaction_count.
`max_connections`	Conexiones HTTPS simultáneas, 1–100 (40 por defecto).
`ip_address`	IP fija en lugar de la resolución DNS.
`certificate`	Clave pública de un certificado autofirmado.
`drop_pending_updates`	Descarta las actualizaciones que esperan en la cola.

Lo mismo con 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"

Con un certificado autofirmado:

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"

Verifica el token secreto en tu servidor

Compara siempre el encabezado con tu secreto y rechaza el resto de solicitudes: la URL del webhook por sí sola no es un secreto.

// 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);
});

Errores frecuentes

Bad Request: bad webhook: An HTTPS URL must be provided for webhook — usa https://.
Bad Request: bad webhook: Webhook can be set up only on ports 80, 88, 443 or 8443 — cambia el puerto o pon un proxy inverso delante.
Bad Request: bad webhook: Failed to resolve host — el dominio no tiene registro DNS público.
Bad Request: secret token contains unallowed characters — usa solo letras, dígitos, _ y -.