Webhooks

Los webhooks permiten recibir notificaciones push automáticas cuando ocurren eventos relevantes en el sistema de evaluación. En lugar de hacer polling periódico a la API, el sistema envía una petición HTTP POST a la URL que la entidad configure.

Cómo funcionan

sequenceDiagram
    participant E as Entidad
    participant API as API T-Canaria
    participant WH as Endpoint Entidad

    E->>API: POST /webhooks (registrar)
    API-->>E: Webhook creado (id: 3)
    Note over API: Tiempo después...
    API->>WH: POST (evaluacion.abierta)
    Note over WH: Cabeceras:<br/>X-Webhook-Event<br/>X-Webhook-Signature
    WH-->>API: 200 OK

Características

Característica	Valor
Protocolo	HTTPS obligatorio
Método	POST
Formato payload	JSON
Firma	HMAC-SHA256 (opcional, vía secreto compartido)
Max webhooks por entidad	5
Eventos disponibles	11
Cabecera de evento	X-Webhook-Event
Cabecera de firma	X-Webhook-Signature

Endpoints disponibles

Método	Endpoint	Descripción
GET	/webhooks/eventos	Listar eventos disponibles
POST	/webhooks	Registrar nuevo webhook
GET	/webhooks	Listar webhooks registrados
DELETE	/webhooks/{id}	Eliminar webhook
POST	/webhooks/test	Probar un webhook

Formato del payload recibido

Cuando se dispara un evento, la entidad recibe un POST con este formato:

POST https://mi-entidad.es/api/webhooks/tcanaria
Content-Type: application/json
X-Webhook-Event: evaluacion.abierta
X-Webhook-Signature: a1b2c3d4e5f6...

{
  "evento": "evaluacion.abierta",
  "timestamp": "2026-03-25T10:00:00Z",
  "data": {
    "evaluacionId": 11,
    "titulo": "Evaluacion ITCanarias 2025"
  }
}

URL HTTPS obligatoria

La URL del webhook debe usar HTTPS. No se aceptan URLs HTTP ni IPs privadas (protección anti-SSRF).

Verificación de firma

Si configura un secreto compartido al registrar el webhook, todas las peticiones incluirán la cabecera X-Webhook-Signature con un HMAC-SHA256 del body. Verifique esta firma para asegurar que la petición proviene del sistema T-Canaria. Ver verificar firma.