Webhooks

Suscríbete a eventos y recibe un POST en tu servidor cada vez que algo pasa en tus filas — sin sondear la API. Crea webhooks desde el panel (Integraciones) o por API (POST /api/v1/webhook-endpoints, scope webhooks:write).

Eventos disponibles

Evento	Cuándo se emite
`turn.created`	Se creó un turno (app, kiosco, panel o API).
`turn.called`	El despachador llamó al turno.
`turn.completed`	El turno fue atendido.
`turn.cancelled`	El turno se canceló (usuario o staff).
`turn.reopened`	Un turno finalizado fue reabierto por el staff.
`queue.opened`	La fila abrió.
`queue.closed`	La fila cerró.
`appointment.scheduled`	Se agendó una cita.
`appointment.completed`	La cita fue atendida.

Formato de la entrega

POST https://tu-servidor.com/webhooks/turno0
X-FilaXPress-Event: turn.created
X-FilaXPress-Delivery: <id de entrega>
X-FilaXPress-Signature: sha256=<hmac hex>

{
  "id": "<id de entrega>",
  "event": "turn.created",
  "data": { "turnId": "...", "queueRunId": "...", "displayCode": "A-012", ... },
  "createdAt": "2026-07-18T17:20:00.000Z"
}

Nota: los headers usan el prefijo técnico X-FilaXPress-* (nombre interno heredado de la plataforma). Responde 2xx en menos de 10 segundos; cualquier otra respuesta marca la entrega como fallida.

Verificar la firma

Al crear el webhook recibes un secreto whsec_… (una sola vez). Cada entrega se firma con HMAC-SHA256 sobre el cuerpo crudo. Rechaza cualquier petición cuya firma no coincida:

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  return timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}

Python

import hashlib, hmac

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature_header, expected)

Buenas prácticas

Procesa la entrega de forma asíncrona y responde 200 de inmediato.
Usa el id de la entrega para deduplicar: una entrega puede repetirse.
Los webhooks son una notificación, no la fuente de verdad: ante dudas consulta la API (GET /api/v1/turns/{turnId}).