Crear un webhook de Discord para publicar mensajes automáticamente

¿Qué es un webhook de Discord?

Un webhook de Discord es una URL específica de un canal que permite a un servicio externo publicar un mensaje en ese canal enviando una solicitud HTTP, sin iniciar sesión como bot ni como usuario. La propia documentación de desarrolladores de Discord describe el endpoint como POST /webhooks/{webhook.id}/{webhook.token} y afirma sin rodeos que "this call does not require authentication" (esta llamada no requiere autenticación), porque el id y el token del webhook incrustados en la URL son en sí mismos la credencial. Ese único hecho explica casi todo lo que un equipo necesita saber sobre su configuración: crear el webhook es un paso puntual dentro de Discord que exige permiso, mientras que usarlo después es tan simple como enviar JSON a una URL.

¿Cómo se crea un webhook de Discord en la configuración del canal?

Un miembro del servidor con el permiso Manage Webhooks crea un webhook de Discord desde la propia configuración de un canal, en la pestaña Integraciones, eligiendo New Webhook y copiando la URL que Discord genera para él. La misma acción está disponible a través de la API de Discord como POST /channels/{channel.id}/webhooks, para la que la documentación de Discord indica que también se requiere el permiso Manage Webhooks en ese canal. Nombra el webhook y, si hace falta, dale un avatar antes de copiar la URL, porque a partir de ese momento cualquiera que tenga esa URL puede publicar en el canal.

¿Cómo es el payload JSON de un webhook de Discord?

El payload JSON de un webhook de Discord es el cuerpo de la solicitud que se envía a la URL del webhook, y como mínimo debe incluir uno de content, embeds, poll o un archivo adjunto, ya que la propia documentación de Discord lo enumera como requisito para la llamada de ejecución del webhook. El campo content lleva texto de mensaje plano de hasta 2000 caracteres, mientras que username y avatar_url sobrescriben el nombre y la imagen predeterminados del webhook solo para ese mensaje, y embeds lleva hasta 10 objetos de embed con formato enriquecido en una sola llamada. El mecanismo es un cuerpo JSON POST estándar: un servicio construye este objeto, lo envía a la URL del webhook por HTTPS, y Discord publica el resultado en el canal donde se creó el webhook.

{
  "content": "Deployment finished",
  "username": "Release Bot",
  "avatar_url": "https://example.com/bot-avatar.png",
  "embeds": []
}

¿Qué límites de tasa se aplican a un webhook de Discord?

Discord aplica un límite global de 50 solicitudes por segundo por aplicación en toda su API, según la propia documentación de desarrolladores de Discord, y la ruta propia de un webhook lleva un límite aparte y más estrecho que Discord comunica a través de encabezados de respuesta en lugar de un único número publicado. Cada respuesta incluye los encabezados X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset, y la documentación de Discord indica a un cliente que lea esos encabezados en vez de fijar un límite en el código, ya que los límites por ruta están "subject to change" (sujetos a cambio). Un servicio que envía muchos mensajes en ráfaga necesita revisar el encabezado de solicitudes restantes después de cada llamada y pausar en cuanto llega a cero, en lugar de asumir un número fijo de llamadas por minuto.

¿Por qué la URL de un webhook de Discord es un secreto?

La URL de un webhook de Discord es un secreto porque el id y el token que contiene son toda la credencial que el endpoint comprueba, y la propia documentación de Discord confirma que la llamada de ejecución del webhook no necesita autenticación adicional más allá de lo que ya lleva la URL. Cualquiera que tenga esa URL puede publicar cualquier mensaje en ese canal, bajo el nombre del webhook, sin autenticarse jamás como usuario de Discord ni como bot. Guarda la URL como se guarda una clave de API, por ejemplo en una variable de entorno o un gestor de secretos, y nunca la subas a un repositorio de código público ni la pegues en un script del lado del cliente.

¿Puede un webhook de Discord recibir mensajes, no solo enviarlos?

Un webhook de Discord estándar solo envía mensajes a un canal; no puede leer los mensajes que otras personas publican allí, ya que el endpoint de ejecución del webhook es un destino POST de una sola vía, sin el acceso de lectura correspondiente. Un equipo que quiera reaccionar a lo que ocurre dentro de un servidor de Discord, del mismo modo en que los límites de tasa de la API de Reddit rigen una integración bidireccional con Reddit, necesita en su lugar un bot de Discord con su propio token y los permisos de gateway pertinentes. Eso es una configuración distinta a la de un webhook, más cercana a cómo los precios de la API de Twitter condicionan el acceso bidireccional a los propios datos de X, y pertenece al lado de recopilación de datos de redes sociales de un proyecto más que al de las alertas; la documentación de desarrolladores de Discord, al estilo de una guía de introducción, es la siguiente parada adecuada para un equipo que construye un bot completo.

Preguntas frecuentes

¿Puedo editar o eliminar un mensaje que ya envié con un webhook de Discord?

Sí. La respuesta de la llamada de ejecución del webhook de Discord devuelve un message id cuando la solicitud incluye ?wait=true, y ese id puede usarse con endpoints separados de edición y eliminación asociados al mismo webhook. Sin wait=true, la llamada inicial no devuelve el objeto de mensaje necesario para una edición posterior.

¿Caduca un webhook de Discord?

La URL de un webhook de Discord no caduca por sí sola; sigue siendo válida hasta que un administrador del servidor elimina el webhook o quita el canal al que pertenece. Como nunca caduca por sí misma, la suposición más segura es tratar la URL como un secreto permanente, no como un token temporal.

¿Pueden varios servicios usar la misma URL de un webhook de Discord?

Sí, técnicamente cualquier número de servicios puede enviar solicitudes a la misma URL de webhook, ya que Discord no distingue qué remitente hizo la llamada. En la práctica, usar un webhook separado por servicio o por bot facilita rastrear los mensajes hasta su origen y permite revocar una integración sin romper otra.

¿Qué pasa si envío un payload más grande que los límites de Discord?

Discord rechaza la solicitud con una respuesta de error en lugar de truncar el contenido en silencio, así que un payload con más de 2000 caracteres en content o más de 10 objetos en embeds hace fallar la llamada por completo. Revisar el código de estado de la respuesta después de cada llamada al webhook detecta esto antes de que un mensaje simplemente nunca llegue.

¿Crear un webhook de Discord requiere específicamente al dueño del servidor?

No. Cualquier miembro con el permiso Manage Webhooks en un canal puede crear un webhook allí, y ese permiso puede concederse a un rol sin convertir a ese rol en dueño ni administrador del servidor. La API de Discord aplica la misma comprobación de permiso en el endpoint POST /channels/{channel.id}/webhooks usado para crear uno de forma programática.

¿Es un webhook de Discord lo mismo que un bot de Discord?

No. Un webhook es una URL de una sola vía para publicar mensajes en un único canal sin inicio de sesión, mientras que un bot es una aplicación completa con su propio token que puede leer mensajes, responder a comandos y actuar en muchos canales y servidores. Un proyecto que solo necesita enviar notificaciones a un canal necesita un webhook; un proyecto que necesita escuchar y responder necesita un bot.

¿Se puede configurar un webhook de Discord sin escribir código?

Crearlo no requiere código: un miembro del servidor con el permiso Manage Webhooks abre la pestaña Integrations del canal, hace clic en New Webhook y copia la URL generada. Ponerle nombre o avatar al webhook en ese momento es opcional. Para enviar un mensaje sí hace falta alguna forma de mandar una solicitud POST por HTTPS con un cuerpo JSON, ya sea un script, una herramienta de automatización o un servicio que ya hable JSON.

¿Cómo sé cuántas solicitudes me quedan antes de tocar el límite de tasa de Discord?

Discord no publica un número fijo para la ruta propia de un webhook; en cambio, cada respuesta incluye los encabezados X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. La propia documentación de Discord indica que un cliente debe leer esos encabezados en lugar de fijar un límite de memoria, porque los límites por ruta pueden cambiar. Un servicio que envía muchos mensajes en ráfaga revisa el encabezado de solicitudes restantes después de cada llamada y se detiene en cuanto llega a cero.

¿Puede un mensaje de webhook parecer que viene de otra persona?

Los campos username y avatar_url del payload JSON sobrescriben el nombre y la imagen por defecto del webhook, pero solo para ese mensaje. El nombre y el avatar configurados del webhook siguen igual en todo lo demás. Esto permite que un webhook publique como "Release Bot" para un aviso de despliegue y con otro nombre la próxima vez, sin tocar la configuración del webhook.

¿Qué impide que otra persona publique en mi canal si consigue mi URL de webhook?

Nada. El id y el token del webhook dentro de la URL son toda la credencial que Discord comprueba, así que cualquiera con esa URL puede publicar cualquier mensaje en el canal bajo el nombre del webhook, sin iniciar sesión como usuario ni como bot. Por eso conviene tratar la URL como una API key: guardarla en una variable de entorno o un gestor de secretos, y no subirla nunca a un repositorio público ni pegarla en código del lado del cliente.