Recibe eventos de TicketWave como solicitudes HTTP firmadas en tu propia aplicación.

Webhooks

Un webhook es una solicitud HTTP que TicketWave te envía. Cada vez que ocurre algo en tu servidor — se abre un ticket, un miembro es incluido en la lista negra — TicketWave hace POST de un cuerpo JSON a una URL que tú controlas.

Esa es la diferencia con Canales de registro: los canales de registro escriben un embed en Discord para que lo lean personas, mientras que los webhooks entregan el evento en bruto a tu código.

Los webhooks son una función premium. Sin premium, no se pueden crear endpoints y no se entrega ningún evento.

Crear un endpoint

Abre la página de endpoints

Panel del servidor → Webhooks → Endpoints.

Añade un endpoint

Haz clic en Add Endpoint y completa dos campos:

Field	Description
Endpoint URL	La URL `https://` que recibe las solicitudes
Event Types	Qué eventos debe recibir este endpoint

Un endpoint solo recibe los tipos que marques. No se permite no seleccionar ninguno: elige al menos uno.

Copia el secreto de firma

TicketWave genera un secreto de firma (whsec_…) en el momento en que se crea el endpoint. Abre la lista de endpoints, muéstralo con el icono del ojo y cópialo en la configuración de tu aplicación.

Trata el secreto como una contraseña. Cualquiera que lo tenga puede falsificar solicitudes que pasen tu comprobación de firma. Guárdalo en una variable de entorno, nunca en tu repositorio.

Envía un evento de prueba

Usa el botón Send test event (el avión de papel) en la fila del endpoint. Entrega una solicitud real, completamente firmada, con "test": true en el payload, para que puedas confirmar que tu receptor funciona antes de que un ticket real dependa de ello.

El resultado aparece en el historial de Webhooks como cualquier otra entrega.

Requisitos del endpoint

Requirement	Detail
Scheme	Solo `https://` — `http://` se rechaza
Host	Debe poder resolverse públicamente. Se rechazan direcciones privadas, loopback, link-local y CGNAT
Response	Cualquier estado `2xx` cuenta como éxito
Timeout	Tienes 10 segundos para responder
Redirects	No se siguen. Un `3xx` cuenta como fallo
Limit	Hasta 5 endpoints por servidor

La comprobación del host se realiza tanto cuando guardas el endpoint como antes de cada entrega, así que un dominio que más tarde empiece a resolver a una dirección interna deja de recibir entregas.

La solicitud

Cada entrega es un POST con un cuerpo JSON.

Headers

Header	Example	Meaning
`Content-Type`	`application/json`	Siempre JSON
`User-Agent`	`TicketWave-Webhooks/1.0.5`	La versión del bot que lo envió
`X-TicketWave-Event`	`ticket.created`	El tipo de evento
`X-TicketWave-Delivery`	`wh_3f2a…`	Id único de esta entrega
`X-TicketWave-Timestamp`	`1786224191`	Segundos Unix, parte de la firma
`X-TicketWave-Signature`	`sha256=9f86d0…`	HMAC de la solicitud

Body

Cada payload usa el mismo contenedor. Solo data cambia según el tipo de evento:

{
  "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"
  }
}

Consulta la Referencia de eventos para ver el objeto data de cada tipo.

Verificar la firma

Cualquiera que descubra la URL de tu endpoint puede enviarle una solicitud POST. La firma es lo que te permite distinguir una entrega real de TicketWave de una falsificada.

Verifica siempre. Un endpoint no verificado que crea o cierra cosas en tu sistema es una puerta abierta.

Cómo se construye la firma

TicketWave une la marca de tiempo y el cuerpo en bruto de la solicitud con un punto, y ejecuta HMAC-SHA256 sobre el resultado usando el secreto de tu endpoint:

signed_payload = X-TicketWave-Timestamp + "." + raw_request_body
signature      = HMAC_SHA256(signed_payload, your_endpoint_secret)

El header lleva ese digest codificado en hexadecimal y con prefijo: sha256=<digest>.

Qué debe hacer tu receptor

Lee el cuerpo en bruto. Verifica contra los bytes exactos que recibiste. Si tu framework analiza primero el JSON y luego lo vuelves a serializar, el orden de las claves o los espacios pueden cambiar y el digest no coincidirá.

Recalcula el HMAC sobre timestamp + "." + rawBody con tu secreto.

Compara en tiempo constante (crypto.timingSafeEqual en Node). Un simple === filtra información de tiempo.

Comprueba que la marca de tiempo sea reciente — cinco minutos de tolerancia es un buen valor por defecto. La marca de tiempo está dentro del payload firmado, así que un atacante no puede reutilizar una solicitud antigua con una marca de tiempo nueva.

Tienes una implementación completa en la página Servidor de ejemplo.

Reintentos

Una entrega que falla se reintenta automáticamente.


Attempts	3 (el primer intento más 2 reintentos)
Backoff	1 segundo, luego 5 segundos
Retried on	Errores de red, timeouts, `408`, `429` y cualquier `5xx`
Not retried on	Cualquier otro `4xx` — eso significa que tu endpoint rechazó la solicitud a propósito

Debido a los reintentos, tu endpoint puede recibir el mismo evento dos veces. Usa X-TicketWave-Delivery como clave de idempotencia: recuerda los ids que ya has procesado e ignora las repeticiones.

Las entregas no están ordenadas. Si dos tickets se crean al mismo tiempo, las solicitudes pueden llegar en cualquier orden — usa el campo timestamp del cuerpo si el orden te importa.

Historial de entregas

La página Webhooks del panel muestra cada entrega con su estado, código de respuesta, duración y número de intentos. Abre una fila para ver el payload exacto de la solicitud que se envió y la respuesta que devolvió tu servidor.

Las entregas fallidas pueden reenviarse desde la página de detalle con Retry Webhook. Envía de nuevo el payload original al mismo endpoint y registra una nueva entrega.

El historial se conserva durante 30 días, y luego se limpia automáticamente.

Solución de problemas

Problem	Fix
No se puede guardar el endpoint	La URL debe ser `https://` y resolver a una dirección pública
Todo aparece como fallido sin código de respuesta	La solicitud nunca llegó a tu servidor — timeout, fallo de DNS o conexión rechazada
La firma nunca coincide	Estás calculando el hash sobre el cuerpo analizado en lugar de los bytes en bruto, o olvidaste el prefijo `timestamp + "."`
Las entregas se detienen al cabo de un tiempo	Comprueba si tu host empezó a devolver `4xx` — esos no se reintentan
Un evento nunca llega	El endpoint no está suscrito a ese tipo, o el servidor perdió premium
Eventos duplicados	Es lo esperado en los reintentos — deduplica usando `X-TicketWave-Delivery`

Siguientes pasos

Referencia de eventos (Cada evento y su payload)
Servidor de ejemplo (Un receptor Express ejecutable)
Canales de registro (Los mismos eventos, pero publicados en Discord)

Resumen