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 forma 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} replican a 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 en el sitio. 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 el canal no elimina el registro del webhook; la siguiente ejecución devuelve 404 por el join con el canal en la consulta.
No se puede sobrescribir username ni avatar_url por petición. La identidad queda fijada al usuario bot.
No se aplica un tope 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 golpees el endpoint en bucles cerrados.
Servidores autoalojados: los webhooks no se reenvían a instancias autoalojadas. Todos los endpoints de webhook devuelven 404 para destinos de guild autoalojados. Consulta la documentación de autoalojado.

← Volver a la documentación