Webhook de Discord vs bot

Webhook y bot se parecen porque ambos hacen aparecer un mensaje en un canal de Discord. La diferencia está en el sentido de la comunicación. El webhook es una puerta de entrada: haces un POST y el mensaje aparece. El bot es un participante: recibe eventos, decide qué hacer y responde.

Elegir mal cuesta tiempo. Quien levanta un bot solo para avisar "despliegue terminado" mantiene un proceso encendido sin necesidad. Quien intenta crear comandos con un webhook descubre tarde que no escucha nada.

¿Qué es un webhook de Discord?#

Es una URL que Discord genera para un canal (en Ajustes del canal, Integraciones, Webhooks). Se llama con POST /webhooks/{id}/{token}, sin cabecera de autenticación: el token dentro de la URL ya es la credencial. Cualquiera que tenga la URL puede publicar en el canal.

Por API, el webhook acepta content (hasta 2000 caracteres), embeds (hasta 10 por mensaje), archivos, encuestas, y username y avatar_url para cambiar el nombre y la foto de cada mensaje. Debes enviar al menos uno entre contenido, embeds, componentes, archivo o encuesta. Con ?wait=true la API devuelve el mensaje creado, y con thread_id publica en un hilo.

Ejemplo mínimo con curl:

curl -X POST "$DISCORD_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"content": "Despliegue terminado", "username": "CI"}'

Lo mismo en Node.js, con el fetch nativo y sin ninguna librería (guárdalo como .mjs, por el await fuera de una función):

const res = await fetch(process.env.DISCORD_WEBHOOK_URL + "?wait=true", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    embeds: [{ title: "Nuevo pedido", description: "Pedido #1234 pagado", color: 0x57f287 }],
  }),
});

if (res.status === 429) {
  const { retry_after } = await res.json();
  console.error(`Límite alcanzado, reintenta en ${retry_after}s`);
} else if (!res.ok) {
  console.error("Falló:", res.status, await res.text());
}

¿Qué es un bot de Discord?#

Es una aplicación con usuario propio, creada en el Portal de Desarrolladores, que se autentica con un token. Puede conectarse al Gateway (una conexión WebSocket) y recibir eventos en tiempo real: mensajes, entrada de miembros, reacciones, comandos de barra. También puede recibir interacciones por HTTP si configuras una Interactions Endpoint URL, sin mantener el Gateway abierto. Con esa URL configurada, las interacciones dejan de llegar por el Gateway. Cada petición al endpoint HTTP trae las cabeceras X-Signature-Ed25519 y X-Signature-Timestamp, y debes validar la firma.

El bot puede hacer casi todo lo que hace un miembro: gestionar roles, moderar, reproducir audio, mostrar menús y botones. Para crear uno, mira cómo hacer un bot de Discord.

Webhook o bot: ¿qué cambia en la práctica?#

Un detalle sobre la lectura: un bot sin el intent privilegiado MESSAGE_CONTENT recibe content vacío en los mensajes, con excepciones como los mensajes que mencionan al bot, los mensajes directos con él y los que envía él mismo. Detalles en intents privilegiados.

¿Cuándo basta con un webhook?#

Elige webhook cuando el flujo es de una sola vía y el disparador viene de fuera de Discord:

• alertas de monitoreo, fallo de build o deploy terminado;
• notificación de venta, registro o pago;
• feed de RSS, commits o changelog en un canal;
• un script de cron que publica un resumen diario.

La ventaja es la simplicidad. No hay token de bot, intents ni reconexión. El costo es que el webhook solo conoce el canal: no sabe quién está ahí, no escucha respuestas y no pasa por permisos de roles.

¿Cuándo necesitas un bot?#

Necesitas un bot en cuanto Discord pasa a ser la entrada del flujo:

• comandos de barra (/ticket, /play), botones y menús;
• moderación, bienvenidas, roles automáticos;
• respuestas que dependen del usuario, del historial o de una base de datos;
• música, voz o cualquier cosa que use el Gateway;
• mensajes en varios servidores o canales elegidos en tiempo de ejecución.

Si el bot debe responder las 24 horas, necesita un proceso siempre encendido. Mira cómo mantener un bot de Discord 24/7.

¿Qué límites afectan a cada uno?#

El límite global de la API es de 50 peticiones por segundo por bot, y las rutas tienen límites propios que Discord pide no fijar en el código. Las peticiones sin cabecera de autorización, como las de webhook, se limitan por IP. Al superarlo, la API responde 429 con retry_after en segundos. Espera el tiempo que indica la cabecera Retry-After o el campo antes de reintentar. El ejemplo de arriba ya lee el campo. Más en error 429 de Discord.

Otro cuidado: si un webhook devuelve 404, deja de usarlo (probablemente fue eliminado). La documentación indica no insistir, porque los reintentos llevan a una restricción temporal.

Los límites de contenido son los mismos en ambos: 2000 caracteres de texto, 10 embeds por mensaje y 6000 caracteres sumados en los textos de los embeds.

¿Se pueden combinar?#

Sí, y muchos proyectos lo hacen. El bot gestiona comandos y eventos dentro del servidor. Los sistemas externos (CI, pasarela de pago, monitor) envían alertas por webhook, sin depender de que el bot esté en línea en ese momento. Si el bot cae, las alertas siguen llegando.

Una regla práctica: empieza con webhook si solo necesitas avisar. Pasa a bot cuando aparezca la primera necesidad de leer o responder.

Cómo hacerlo en Square Cloud#

El webhook no necesita hosting, pero el código que lo dispara tiene que ejecutarse en algún sitio. El bot de Gateway, en cambio, necesita un proceso siempre encendido. En Square Cloud los contenedores no entran en modo de suspensión, y el reinicio automático (activado por defecto en el deploy desde el panel) vuelve a levantar el bot cuando el proceso termina con error.

Despliegas el bot en Node.js, Python, Java u otro runtime con un ZIP en el panel, la CLI, GitHub o la extensión de VS Code. La RAM del plan es un pool compartido entre tus aplicaciones, con un mínimo de 256 MB por aplicación en segundo plano, como un bot. El plan Hobby cuesta desde R$12,49 al mes. Guarda el token del bot y la URL del webhook como variables de entorno de la aplicación, no en el código.

Para empezar, consulta la página de hosting para bots de Discord.