Cuándo usar un webhook
Usa un webhook para notificaciones de compilación, eventos de servicios externos o actualizaciones. Publica en un canal de texto preseleccionado. Para leer mensajes, gestionar comandos y botones o reaccionar a eventos, usa un bot.
Crear un webhook
Abre los ajustes del canal de texto → Webhooks · mensajes automatizados. Crear y eliminar webhooks requiere MANAGE_CHANNELS. Guarda la ruta y el token devueltos: el secreto solo se muestra una vez y en la base de datos solo se guarda su hash.
| Token de cuenta | Operación |
|---|---|
| GET /api/channels/:channelId/webhooks | Listar webhooks. |
| POST /api/channels/:channelId/webhooks | {name, author_name?, avatar_url?} → 201 {webhook, token, path}. |
| DELETE /api/channels/:channelId/webhooks/:id | Eliminar un webhook. |
La dirección y el identificador pertenecen a la API del anfitrión del canal. Los webhooks no admiten mensajes directos, grupos ni espacios públicos.
Enviar
POST /api/webhooks/:id/execute
Authorization: Bearer <WEBHOOK_TOKEN>
Content-Type: application/json
{ "embeds": [{
"title": "Compilación lista",
"description": "La versión está lista para revisión.",
"color": 5793266,
"fields": [{ "name": "Estado", "value": "Listo", "inline": true }]
}] }También se admite {"content":"Texto"}, hasta 2000 caracteres. Hasta 10 embeds y 6000 caracteres en total. Cuando el texto acompaña a los embeds, ocupa una de las ranuras. Una respuesta 201 correcta contiene el id del mensaje y channel_id. El canal se define en la configuración, no en el cuerpo de la solicitud.
Límites y seguridad
- Una solicitud aceptada por webhook cada 2 segundos. Ante un 429, usa Retry-After: 2.
- El autor y el avatar se fijan al crear el webhook, no los elige cualquier remitente. Los mensajes se marcan como webhooks.
- Los permisos del creador se comprueban al enviar. Perder permisos puede producir un 403.
- No repitas una solicitud cuyo resultado desconoces sin comprobar antes: la idempotencia no está implementada.
- Envía el secreto en Authorization, no en la URL. Elimina y vuelve a crear un webhook si su secreto se filtra.
- Evita datos personales en las notificaciones y las URL de imágenes externas.