Registrar webhook

POST /apientidades/v1/webhooks

Registra un nuevo webhook para recibir notificaciones push de eventos del sistema de evaluación.

Body de la petición

{
  "url": "https://mi-entidad.es/api/webhooks/tcanaria",
  "eventos": ["evaluacion.abierta", "resultados.definitivos", "documento.disponible"],
  "secreto": "mi-secreto-compartido-seguro-12345"
}

Campos del body

Campo	Tipo	Obligatorio	Descripción
url	string	Sí	URL HTTPS del endpoint que recibirá las notificaciones (POST)
eventos	array	Sí	Lista de eventos a los que suscribirse (mínimo 1)
secreto	string	No	Secreto compartido para firmar los payloads con HMAC-SHA256 (max 512 chars)

Ejemplo de petición

curlPythonC#

curl -s -X POST \
  "https://apientidades-pro.transparenciacanarias.org/apientidades/v1/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mi-entidad.es/api/webhooks/tcanaria",
    "eventos": [
      "evaluacion.abierta",
      "resultados.provisionales",
      "resultados.definitivos",
      "documento.disponible",
      "incidencia.respuesta"
    ],
    "secreto": "mi-secreto-compartido-seguro-12345"
  }' | jq .

import requests

BASE_URL = "https://apientidades-pro.transparenciacanarias.org/apientidades/v1"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

payload = {
    "url": "https://mi-entidad.es/api/webhooks/tcanaria",
    "eventos": [
        "evaluacion.abierta",
        "resultados.definitivos",
        "documento.disponible"
    ],
    "secreto": "mi-secreto-compartido-seguro-12345"
}

response = requests.post(
    f"{BASE_URL}/webhooks",
    headers=headers,
    json=payload
)

if response.status_code == 201:
    webhook = response.json()
    print(f"Webhook creado: ID {webhook['id']}")
else:
    print(f"Error: {response.json()}")

var payload = new
{
    url = "https://mi-entidad.es/api/webhooks/tcanaria",
    eventos = new[] { "evaluacion.abierta", "resultados.definitivos", "documento.disponible" },
    secreto = "mi-secreto-compartido-seguro-12345"
};

var content = new StringContent(
    JsonConvert.SerializeObject(payload), Encoding.UTF8, "application/json");
var response = await client.PostAsync($"{baseUrl}/webhooks", content);

if (response.StatusCode == HttpStatusCode.Created)
{
    var webhook = JsonConvert.DeserializeObject<dynamic>(
        await response.Content.ReadAsStringAsync());
    Console.WriteLine($"Webhook creado: {webhook.id}");
}

Respuesta exitosa (201 Created)

{
  "id": 3,
  "url": "https://mi-entidad.es/api/webhooks/tcanaria",
  "eventos": ["evaluacion.abierta", "resultados.definitivos", "documento.disponible"],
  "activo": true,
  "fechaAlta": "2026-03-25T14:30:00Z"
}

Campo	Tipo	Descripción
id	int	ID del webhook creado
url	string	URL registrada
eventos	array	Eventos suscritos
activo	bool	Si el webhook está activo
fechaAlta	datetime	Fecha de creación (ISO 8601)

Validaciones

Validación	Límite	Error
URL obligatoria	No vacía	400
URL HTTPS	Debe empezar por https://	400
URL longitud	Max 2.000 caracteres	400
URL no privada	No IPs privadas (10.x, 172.16-31.x, 192.168.x, localhost)	400
Eventos	Al menos 1	400
Eventos válidos	Solo de la lista de 11 eventos	400 "Eventos no válidos: ..."
Secreto	Max 512 caracteres	400
Max webhooks	5 por entidad	400 "Máximo 5 webhooks"

Protección SSRF

La API valida que la URL no apunte a redes privadas ni a localhost. Esto previene ataques Server-Side Request Forgery (SSRF). Las siguientes URLs se rechazan:

• https://localhost/...
• https://127.0.0.1/...
• https://10.0.0.1/...
• https://192.168.1.1/...
• https://172.16.0.1/...

Secreto compartido

Se recomienda encarecidamente proporcionar un secreto para poder verificar la autenticidad de las notificaciones. Ver verificar firma.

Listar webhooks registrados

GET /apientidades/v1/webhooks

[
  {
    "id": 3,
    "url": "https://mi-entidad.es/api/webhooks/tcanaria",
    "eventos": ["evaluacion.abierta", "resultados.definitivos"],
    "activo": true,
    "fechaAlta": "2026-03-25T14:30:00Z",
    "ultimaEjecucion": "2026-03-25T18:00:00Z",
    "ultimoEstado": 200,
    "ultimoError": ""
  }
]

Campo	Tipo	Descripción
ultimaEjecucion	datetime?	Fecha de la última ejecución del webhook
ultimoEstado	int?	Código HTTP de la última respuesta
ultimoError	string	Mensaje de error de la última ejecución (vacío si fue exitosa)

Eliminar webhook

DELETE /apientidades/v1/webhooks/{id}

{
  "message": "Webhook eliminado."
}

Errores posibles

Código	Descripción
400	Validación fallida (ver tabla)
401	Token ausente, expirado o inválido
404	El webhook no existe o no pertenece a la entidad (DELETE)