Webhooks

Los webhooks permiten que Keues avise a tu propio sistema cada vez que ocurre algo con un turno. En lugar de consultar la API continuamente, Keues envía una petición HTTP a la URL que indiques en el momento en que sucede el evento.

Así puedes conectar Keues con tu TPV, tu CRM, una pantalla externa, tu sistema de analítica o cualquier otra herramienta que necesite saber qué está pasando.

Configuración

Los webhooks se configuran en el dashboard, en Ajustes → Webhooks. Solo los usuarios con rol de administrador pueden ver y cambiar esta sección.

Campo	Descripción
Activar webhooks	Interruptor general. Mientras esté desactivado no se envía ninguna petición, aunque haya eventos marcados.
URL del webhook	Dirección https://… a la que Keues enviará las peticiones POST.
Key	Clave secreta que Keues envía en la cabecera X-Keues-Key para que puedas comprobar que la petición es tuya.
Eventos suscritos	Lista de eventos que quieres recibir. Solo se envían los que marques.

Precaución

La configuración de webhooks es única por instalación: se aplica a todas las ubicaciones. No se configura una URL distinta por ubicación. Si necesitas separar destinos, usa un endpoint propio que reciba todo y reparta según el campo location del payload.

Eventos disponibles

Evento	Cuándo se envía
Ticket.Created	Se crea un ticket nuevo.
Ticket.Called	Un puesto llama a un ticket.
Ticket.Attended	Termina la atención de un ticket.
Ticket.Transferred	Un ticket se transfiere a otro puesto.
Ticket.Canceled	Se cancela un ticket.

Marca solo los eventos que realmente necesites. Keues no ejecuta el envío de los eventos que no estén suscritos.

Ejemplo de petición

Keues hace un POST a tu URL con el cuerpo en JSON y estas cabeceras:

POST https://tu-servidor.com/webhook HTTP/1.1
Content-Type: application/json
X-Keues-Key: tu-clave-secreta

Ejemplo de cuerpo para Ticket.Called:

{
  "eventType": "Ticket.Called",
  "occurredAt": "2026-11-07T10:24:35.120Z",
  "data": {
    "id": "3f2b9c1e-8a4d-4c6e-9b1a-2d7f5e8c0a11",
    "code": "A-042",
    "queue": {
      "id": "b1d4e6f8-2a3c-4d5e-8f90-1a2b3c4d5e6f",
      "name": "Pescadería"
    },
    "counter": {
      "id": "c2e5f7a9-3b4d-5e6f-9012-2b3c4d5e6f70",
      "name": "Caja 2"
    },
    "user": {
      "id": "d3f6a8b0-4c5e-6f70-8123-3c4d5e6f7081",
      "name": "Ana García",
      "externalId": "ana.garcia"
    },
    "location": {
      "id": "e4a7b9c1-5d6f-7081-9234-4d5e6f708192",
      "name": "Mercado Central"
    }
  }
}

Campos del payload

Campo	Tipo	Descripción
eventType	string	Uno de los eventos de la tabla anterior.
occurredAt	string	Fecha y hora del evento en formato ISO 8601 (UTC).
data.id	string	Identificador interno del ticket.
data.code	string	Código del ticket tal y como se muestra al cliente (por ejemplo A-042).
data.queue	object	Cola del ticket: id y name.
data.counter	object | null	Puesto implicado en el evento: id y name. Puede ser null, por ejemplo al crear el ticket.
data.user	object | null	Usuario que realizó la acción: id, name y externalId. Puede ser null si la acción no está asociada a un usuario.
data.location	object	Ubicación del ticket: id y name.

El campo externalId del usuario está pensado para enlazar con tu propio sistema: puedes guardarlo en Keues y usarlo aquí para identificar a la misma persona sin depender del identificador interno.

Seguridad

Keues no firma el cuerpo con HMAC. La seguridad se basa en la clave compartida enviada en la cabecera X-Keues-Key:

1. Define una clave larga y aleatoria en Ajustes → Webhooks.
2. Configura la misma clave en tu servidor.
3. Rechaza cualquier petición cuya cabecera X-Keues-Key no coincida.

app.post('/webhook', (req, res) => {
  if (req.get('X-Keues-Key') !== process.env.KEUES_WEBHOOK_KEY) {
    return res.sendStatus(401);
  }

  const { eventType, occurredAt, data } = req.body;

  // Procesa el evento sin bloquear la respuesta.
  console.log(eventType, data.code);

  res.sendStatus(204);
});

Consejo

Usa siempre https:// para la URL del webhook y guarda la clave como variable de entorno, nunca en el código.

Entrega y errores

• Keues espera 10 segundos como máximo a que tu servidor responda.
• Se considera entregado si tu servidor responde con un código 2xx.
• No hay reintentos automáticos: si tu servidor no está disponible o tarda demasiado, ese aviso se pierde. Para no perder eventos, responde rápido (2xx) y procesa el trabajo en segundo plano.
• Los envíos correctos y fallidos quedan registrados en el log del servidor de Keues.

API de configuración

Además de la pantalla de Ajustes, la configuración se puede gestionar por API. Todos estos endpoints requieren rol de administrador:

Método	Ruta	Descripción
GET	/api/WebhooksConfig	Obtiene la configuración actual.
PUT	/api/WebhooksConfig	Actualiza url, key, events y enabled.
GET	/api/WebhooksConfig/events	Devuelve la lista de eventos disponibles.

Ejemplo de PUT:

{
  "url": "https://tu-servidor.com/webhook",
  "key": "tu-clave-secreta",
  "events": ["Ticket.Created", "Ticket.Called"],
  "enabled": true
}

Casos de uso

• Sincronizar con el TPV o el ERP cuando se atiende un turno.
• Mostrar el estado en otra pantalla fuera del monitor de Keues.
• Medir tiempos de espera y atención en tu herramienta de analítica.
• Avisar a un responsable cuando se cancela un ticket o se acumula la espera.
• Enlazar usuarios con tu sistema mediante externalId.