Webhooks

No disponible en producción

La versión productiva actual no expone rutas /api/webhooks ni una consola para registrar webhooks. Esta página queda como referencia de diseño futuro; no debe usarse como guía de integración vigente.

¿Qué son los Webhooks?

Los webhooks permiten que el sistema CECOM envíe notificaciones automáticas a sistemas externos cuando ocurren eventos importantes.

sequenceDiagram
  participant CECOM as CECOM API
  participant WH as Webhook Endpoint
  participant EXT as Sistema Externo

  Note over CECOM: Evento ocurre
  CECOM->>WH: POST /su-endpoint
  WH->>EXT: Procesar evento
  EXT->>WH: OK
  WH->>CECOM: 200 OK

Eventos Propuestos (No Disponibles)

Evento	Descripción
emergency.created	Nueva emergencia creada
emergency.updated	Emergencia actualizada
emergency.closed	Emergencia cerrada
resource.dispatched	Recurso despachado
resource.status_changed	Cambio de estado de recurso
shift_handover.completed	Entrega de turno completada
alert.created	Nueva alerta de despacho

Formato del Payload

Estructura General

{
  "event": "emergency.created",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "tenantId": "uuid-del-tenant",
  "data": {
    // Datos específicos del evento
  }
}

Ejemplo: Nueva Emergencia

{
  "event": "emergency.created",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "tenantId": "abc123",
  "data": {
    "id": "em-456",
    "type": "10-1",
    "description": "Incendio forestal sector norte",
    "location": {
      "lat": -33.4489,
      "lng": -70.6693,
      "address": "Sector Norte"
    },
    "status": "ACTIVE",
    "createdBy": "usuario@brysa.cl"
  }
}

Configuración Propuesta (No Disponible)

Registrar Webhook

POST /api/webhooks
Authorization: Bearer <token>
Content-Type: application/json

{
  "url": "https://su-sistema.com/webhooks/cecom",
  "events": ["emergency.created", "emergency.closed"],
  "secret": "clave-para-firma"
}

Respuesta

{
  "success": true,
  "data": {
    "id": "wh-789",
    "url": "https://su-sistema.com/webhooks/cecom",
    "events": ["emergency.created", "emergency.closed"],
    "active": true,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Seguridad

Verificación de Firma

Cada request incluirá un header de firma:

X-CECOM-Signature: sha256=abc123def456...

Validar Firma

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return `sha256=${expected}` === signature;
}

Reintentos

Si el endpoint no responde con 2xx, el sistema reintentará:

Intento	Delay
1	Inmediato
2	1 minuto
3	5 minutos
4	30 minutos
5	2 horas

Después de 5 intentos fallidos, el webhook se marca como inactivo.

WebSocket Alternativo

Mientras los webhooks están en desarrollo, puede usar WebSocket para recibir actualizaciones en tiempo real:

const socket = io('wss://api.cecom-brysa.cl', {
  auth: {
    token: 'su-jwt-token'
  }
});

socket.on('emergency:created', (data) => {
  console.log('Nueva emergencia:', data);
});

socket.on('resource:updated', (data) => {
  console.log('Recurso actualizado:', data);
});

Eventos WebSocket Actuales

Evento	Descripción
emergency:created	Nueva emergencia
emergency:message	Nuevo mensaje en bitácora
resource:updated	Cambio de estado de recurso
attendance:marked	Asistencia registrada

---

Solicitar Acceso

Para participar en el programa beta de webhooks, contacte a contacto@nfr-innovacionesweb.cl