Webhooks de la app

Un webhook de app es una URL por canal a la que tu runner de CI, tu herramienta de monitorización o un servicio externo pueden hacer POST para dejar un mensaje en un canal de GameVox. Sin sesión de gateway. Los mensajes se publican como tu usuario bot, con su avatar y su nombre.

Límites

50 webhooks por aplicación.
Nombre: 1–80 caracteres.
Contenido: 1–4000 caracteres por mensaje.
Un webhook = un canal. Crear un webhook requiere el permiso manage_server en el servidor del canal.

Formato del token

WH.{prefijo de 8 caracteres}.{aleatorio en base64}

ejemplo: WH.aB7xZ2k1.q9F7v1NkN3J2Wm8L6PpV5cU0Yr1zQbXa

El token completo se muestra exactamente una vez, al crearlo. Solo guardamos el hash bcrypt más el prefijo y los últimos 4 caracteres para mostrarlos. Si pierdes un token, elimina el webhook y crea uno nuevo.

Crear un webhook (portal)

Abre tu aplicación → pestaña Webhooks → Nuevo webhook. Elige un servidor que puedas gestionar, elige un canal y ponle un nombre. El diálogo muestra el token completo y la URL de ejecución lista para pegar. Cópiala antes de cerrarlo; el portal no volverá a mostrarla.

Endpoints

Dos modos de autenticación: token del bot para la gestión y token en la URL para la ejecución.

Autenticación por token de bot (gestión)

GET    /channels/{channel.id}/webhooks
POST   /channels/{channel.id}/webhooks
GET    /guilds/{guild.id}/webhooks
GET    /webhooks/{webhook.id}
PATCH  /webhooks/{webhook.id}
DELETE /webhooks/{webhook.id}

Autenticación por token en la URL (ejecutar + editar)

POST   /webhooks/{webhook.id}/{token}
GET    /webhooks/{webhook.id}/{token}
PATCH  /webhooks/{webhook.id}/{token}
DELETE /webhooks/{webhook.id}/{token}
PATCH  /webhooks/{webhook.id}/{token}/messages/{message.id}
DELETE /webhooks/{webhook.id}/{token}/messages/{message.id}

En las rutas con token en la URL no hay cabecera Authorization. El token de la ruta es la autenticación. Trata la URL como un secreto.

Petición de ejecución

Cuerpo JSON:

POST https://api.gamevox.com/webhooks/{webhook.id}/{token}
Content-Type: application/json

{
  "content": "La compilación #4811 pasó en producción.",
  "embeds": [
    {
      "title": "CI en verde",
      "url": "https://ci.example.com/builds/4811",
      "description": "42 pruebas, 0 fallos.",
      "color": 3066993
    }
  ]
}

Cuerpo multipart/form-data (para adjuntos):

Content-Type: multipart/form-data; boundary=xyz

--xyz
Content-Disposition: form-data; name="payload_json"

{ "content": "Ver captura", "embeds": [ ... ] }
--xyz
Content-Disposition: form-data; name="files[0]"; filename="crash.png"
Content-Type: image/png

...binary...
--xyz--

Respuesta (con ambos tipos de contenido):

{
  "id": "1199283740192847400",
  "channel_id": "1199283740192847000",
  "content": "La compilación #4811 pasó en producción.",
  "embeds": [ ... ],
  "attachments": [ ... ],
  "timestamp": "2026-05-21T15:42:09Z"
}

Qué está admitido

Contenido: texto plano, 1–4000 caracteres.
Embeds: la estructura completa de embed de Discord (title, description, url, color, timestamp, footer, image, thumbnail, author, fields). Se permiten varios embeds por mensaje.
Adjuntos: sube archivos con multipart/form-data y una parte payload_json; la respuesta incluye URLs de CDN.
Responder a un mensaje: pasa message_reference en payload_json.
?wait=true: implícito; la respuesta es siempre el mensaje resuelto.
Editar / eliminar: PATCH / DELETE en /webhooks/{id}/{token}/messages/{message.id} funcionan igual que en Discord.
Sobrescribir nombre o avatar: no está admitido. Los mensajes se publican siempre como el usuario bot de la aplicación.

Errores

401: falta el token, está mal formado o no coincide.
404: webhook eliminado o el id no existe.
400: content vacío y sin embeds ni adjuntos, o content de más de 4000 caracteres.
405: verbo no admitido en esta ruta.
413: el adjunto supera el límite de tamaño por archivo.

Rotación

En v1 no hay un endpoint para rotar el token sin recrear el webhook. Elimina el webhook y crea uno nuevo. El token antiguo deja de funcionar de inmediato al eliminarlo (la ruta de ejecución excluye las filas con borrado lógico).

Diferencias con Discord

Los webhooks son propiedad de la aplicación, no de la administración del servidor. Eliminar un canal en la nube elimina sus webhooks. En un servidor autoalojado el registro del webhook sobrevive a un canal eliminado, y ejecutarlo falla porque la instancia ya no tiene el canal.
No se puede sobrescribir username ni avatar_url por petición. La identidad queda fijada al usuario bot.
No se aplica un tope de webhooks por canal; el tope es por aplicación (50).
La autenticación se verifica con bcrypt, así que la comparación del token es lenta a propósito. No satures el endpoint en bucles cerrados.
Servidores autoalojados: los webhooks funcionan igual que en la nube. Los registros de los webhooks viven en la nube, los permisos para gestionarlos los comprueba la instancia del cliente y los mensajes ejecutados se escriben en el canal autoalojado. Consulta la documentación de servidores autoalojados.

← Volver a la documentación