Referencia de eventos
Cada tipo de evento de webhook y el payload exacto que envía TicketWave.
Referencia de eventos
Se pueden suscribir seis tipos de eventos por endpoint. Cada solicitud usa el mismo contenedor — event, timestamp, guild_id y data — y solo cambia el objeto data.
| Event | Fires when |
|---|---|
ticket.created | Se abre un ticket |
ticket.closed | Se cierra un ticket |
ticket.updated | Cambia cualquier otra cosa en un ticket abierto |
message.sent | Un miembro o el staff escribe en un ticket |
blacklist.added | Un miembro es añadido a la lista negra |
blacklist.removed | Se elimina una entrada de la lista negra |
Los campos que no se pueden resolver se envían como null en lugar de omitirse, así que puedes confiar en que las claves existen. Un username es null cuando Discord no devolvió el usuario.
Campos compartidos
Todos los eventos de ticket incluyen estos campos:
| Field | Type | Description |
|---|---|---|
ticket_id | string | El id legible del ticket según tu patrón, por ejemplo ticket-1042 |
ticket_num_id | number | El número correlativo del ticket, por ejemplo 1042 |
channel_id | string | El canal de Discord del ticket |
category | string | null | Nombre de la categoría, null si el ticket no tiene ninguna |
user | object | null | El propietario del ticket como { id, username } |
ticket.created
Se envía justo después de que exista el canal del ticket.
{
"event": "ticket.created",
"timestamp": "2026-08-26T08:23:11.000Z",
"guild_id": "123456789012345678",
"data": {
"ticket_id": "ticket-1042",
"ticket_num_id": 1042,
"channel_id": "998877665544332211",
"category": "🤖 Support",
"user": { "id": "987654321098765432", "username": "Luna" },
"created_at": "2026-08-26T08:23:11.000Z"
}
}Esto se activa cuando el ticket se abre, es decir, antes de que el miembro haya escrito nada. Si necesitas el primer mensaje, escucha también message.sent.
ticket.closed
{
"event": "ticket.closed",
"timestamp": "2026-08-26T07:45:02.000Z",
"guild_id": "123456789012345678",
"data": {
"ticket_id": "ticket-1041",
"ticket_num_id": 1041,
"channel_id": "998877665544332211",
"category": "💸 Payment",
"user": { "id": "987654321098765432", "username": "Luna" },
"closed_by": { "id": "112233445566778899", "username": "Staff_01" },
"reason": "Issue resolved",
"closed_at": "2026-08-26T07:45:02.000Z"
}
}| Field | Type | Description |
|---|---|---|
closed_by | object | Quién lo cerró. Los cierres automáticos informan al bot |
reason | string | null | El motivo del cierre, null si no se indicó ninguno |
ticket.updated
El evento comodín para cambios en un ticket abierto. action te dice qué cambió, changes contiene los detalles de esa acción concreta.
{
"event": "ticket.updated",
"timestamp": "2026-08-26T14:02:19.000Z",
"guild_id": "123456789012345678",
"data": {
"ticket_id": "ticket-1038",
"ticket_num_id": 1038,
"channel_id": "998877665544332211",
"category": "🤖 Support",
"user": { "id": "987654321098765432", "username": "Luna" },
"action": "ticket_priority:add",
"changes": { "priority": "high" },
"reason": null,
"updated_by": { "id": "112233445566778899", "username": "Staff_01" }
}
}Posibles valores de action
action | Meaning | changes contains |
|---|---|---|
ticket_claim:add | Un miembro del staff reclamó el ticket | (empty) |
ticket_unclaim:add | Se liberó la reclamación | (empty) |
ticket_priority:add | Cambió la prioridad | priority |
ticket_rename:add | Se renombró el canal | new_name |
ticket_remind:add | Se envió un recordatorio | (empty) |
ticket_feedback:add | El miembro valoró el ticket | star_count, feedback |
ticket_schedule_close:add | Se programó un cierre | duration, schedule_time |
ticket_request_close:add | El staff pidió al miembro que cerrara | duration, request_duration_time |
ticket_request_close_accept:add | El miembro aceptó | (empty) |
ticket_request_close_deny:add | El miembro rechazó | (empty) |
ticket_close_cancel:add | Se canceló un cierre en curso | (empty) |
ticket_additional_access:add | Se añadió un usuario o rol al ticket | entity_type, entity_id, reason |
ticket_additional_access:remove | Se eliminó un usuario o rol | entity_type, entity_id, reason |
Trata esta lista como abierta. Se añaden nuevas acciones a medida que TicketWave crece, y llegan como ticket.updated. Haz un switch sobre las acciones que te interesen e ignora el resto en lugar de lanzar un error con valores desconocidos.
Responder a un paso del ticket no produce un evento. De lo contrario, un ticket con muchos pasos inundaría tu endpoint mientras el miembro sigue rellenando el formulario.
message.sent
Se envía por cada mensaje humano dentro de un ticket abierto. Los mensajes de bots — incluido el propio TicketWave — se omiten.
{
"event": "message.sent",
"timestamp": "2026-08-26T22:10:55.000Z",
"guild_id": "123456789012345678",
"data": {
"ticket_id": "ticket-1040",
"ticket_num_id": 1040,
"channel_id": "998877665544332211",
"message_id": "1234567890123456789",
"content": "Hello, how can I help you?",
"author": { "id": "112233445566778899", "username": "Staff_01" },
"is_staff": true,
"sent_at": "2026-08-26T22:10:55.000Z"
}
}| Field | Type | Description |
|---|---|---|
content | string | El texto bruto del mensaje. Vacío en mensajes solo con adjuntos |
author | object | { id, username } del remitente |
is_staff | boolean | true si el remitente tiene un rol de soporte configurado |
Este es, con diferencia, el evento de mayor volumen: en un servidor activo se genera una solicitud por mensaje. Suscríbete solo si realmente necesitas datos a nivel de mensaje, y asegúrate de que tu receptor responda rápido.
blacklist.added
No está vinculado a un ticket, así que este payload no tiene ticket_id.
{
"event": "blacklist.added",
"timestamp": "2026-08-26T18:33:47.000Z",
"guild_id": "123456789012345678",
"data": {
"user": { "id": "111223344556677889", "username": "BadActor" },
"reason": "Spam",
"added_by": { "id": "112233445566778899", "username": "Staff_01" }
}
}blacklist.removed
{
"event": "blacklist.removed",
"timestamp": "2026-08-26T18:40:12.000Z",
"guild_id": "123456789012345678",
"data": {
"user": { "id": "111223344556677889", "username": "BadActor" },
"removed_by": { "id": "112233445566778899", "username": "Staff_01" }
}
}Eventos de prueba
El botón Send test event entrega una solicitud real y firmada cuyo data es simplemente:
{
"event": "ticket.created",
"timestamp": "2026-08-26T12:00:00.000Z",
"guild_id": "123456789012345678",
"data": { "test": true }
}El event es el primer tipo al que está suscrito el endpoint. Comprueba data.test si quieres omitir las entregas de prueba en la lógica de producción.
Siguientes pasos
- Example Server (Gestiona estos payloads en Express)
- Webhooks (Firma, reintentos e historial de entregas)
How is this guide?