Webhooks

Los webhooks de SitEat te permiten recibir eventos en tiempo real en tu sistema cuando ocurren acciones relevantes (reservas, lista de espera, etc.).

Gestión desde el panel

En esta fase, la configuración de webhooks y certificados se realiza desde el panel /developer (tabs Webhooks y Certificados), no desde la API pública.

---

1. Configuración en SitEat

1. Entra en /developer → Webhooks.
2. Crea un endpoint webhook con:
   • Nombre
   • URL destino (HTTPS en producción)
   • Eventos a suscribir
   • Estado Activo / Inactivo
3. (Recomendado) Activa Validación por payload y selecciona un certificado.
4. En /developer → Certificados, descarga la clave pública .pem del certificado seleccionado.

La clave pública es la que usarás para verificar la firma en tu backend.

---

2. Eventos disponibles

Reservas

Evento	Descripción
reservas.created	Nueva reserva creada
reservas.updated	Reserva modificada
reservas.cancelled	Reserva cancelada
reservas.deleted	Reserva eliminada

Lista de espera (Waitlist)

Evento	Descripción
waitlist.created	Nueva entrada en lista de espera
waitlist.updated	Entrada modificada
waitlist.called	Cliente llamado
waitlist.seated	Cliente sentado
waitlist.cancelled	Entrada cancelada
waitlist.no_show	Cliente no se presentó

---

3. Request entrante

SitEat envía un POST con Content-Type: application/json.

Headers estándar

Header	Descripción
X-SitEat-Event-Id	ID único del evento
X-SitEat-Event-Type	Tipo de evento (ej. reservas.updated)
X-SitEat-Timestamp	Timestamp ISO del envío
X-SitEat-Delivery-Id	ID único del intento de entrega

Headers de firma (cuando está activada)

Header	Descripción
X-SitEat-Signature	Firma Base64 del body
X-SitEat-Signature-Alg	Algoritmo usado: ed25519
X-SitEat-Certificate-Id	ID del certificado usado para firmar

---

4. Formato del payload

{
  "version": "v1",
  "event_id": "7b2e2c34-....",
  "event_type": "reservas.updated",
  "occurred_at": "2026-04-20T10:02:31.000Z",
  "tenant_id": 35,
  "data": {
    "id": 605,
    "estado": "confirmada"
  }
}

nota

• En eventos updated, data puede incluir un snapshot con before y after.
• Trata data como un objeto versionable: puede crecer con nuevos campos en futuras versiones.

---

5. Verificación de firma (Ed25519)

Si activas la validación por payload, verifica la firma antes de procesar el evento.

Recomendaciones

• Usa el raw body exacto recibido (bytes sin modificar).
• Verifica con la clave pública .pem descargada desde SitEat.
• Rechaza la petición (401 / 400) si la firma no es válida.

Ejemplo — Node.js (crypto nativo)

import crypto from "node:crypto";

export function verifySitEatWebhook({ rawBodyBuffer, signatureBase64, publicKeyPem }) {
  if (!signatureBase64) return false;

  const signature = Buffer.from(signatureBase64, "base64");
  return crypto.verify(
    null,            // Ed25519 no necesita hash separado
    rawBodyBuffer,   // raw body exacto del request
    publicKeyPem,
    signature
  );
}

---

6. Respuesta esperada y reintentos

Devuelve un 2xx cuando proceses correctamente el evento.

Si tu servidor devuelve un error o supera el timeout, SitEat reintentará automáticamente siguiendo esta política:

Intento	Espera
1	1 minuto
2	5 minutos
3	30 minutos
4	2 horas
5	6 horas

Timeout de entrega

SitEat espera respuesta en un máximo de 5 segundos. Si tu lógica es pesada, responde 2xx de inmediato y procesa en una cola interna.

---

7. Idempotencia

Tu endpoint debe ser idempotente: si SitEat reintenta el mismo evento, no debes procesarlo dos veces.

Recomendación:

• Guarda X-SitEat-Event-Id (o X-SitEat-Delivery-Id) en una tabla de eventos procesados.
• Si recibes el mismo ID, responde 200 sin reprocesar.

---

8. Buenas prácticas

• Usa un endpoint HTTPS público y estable.
• Responde rápido (2xx) y delega el procesamiento a una cola interna si es necesario.
• Verifica la firma si está activada.
• Implementa deduplicación por event_id.
• Registra logs por event_id y delivery_id para facilitar el soporte y el debug.

---

9. Checklist de integración

• Crear el endpoint webhook en /developer.
• Suscribir los eventos necesarios.
• Crear un certificado y descargar la clave pública.
• Implementar verificación Ed25519.
• Implementar idempotencia por event_id.
• Probar con un endpoint de test y revisar las entregas en el panel.