API de lectura

Cada entrega es un POST con este cuerpo:

{
  "id": "0f3a…",                 // Alethexis-Event-Id
  "type": "section.closed",
  "created_at": "2026-09-18T09:12:03.412Z",
  "api_version": "v1",
  "data": { "account_id": "…", "section_id": "GOB-2", "status": "complete", "closed_at": "…" }
}

Cabeceras: Alethexis-Signature, Alethexis-Event-Id, Alethexis-Event-Type y User-Agent: Alethexis-Webhooks/1.

Firma

El valor v1 es el HMAC-SHA256 de la marca de tiempo, un punto y el cuerpo exacto que recibes, con el secreto del endpoint. Compara en tiempo constante y rechaza lo que llegue con más de cinco minutos de diferencia.

Verificación:

// Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const [t, v1] = header.split(',').map((part) => part.split('=')[1]);
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false;

  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
  const received = Buffer.from(v1, 'hex');
  return expected.length === received.length && timingSafeEqual(expected, received);
}

# Python
import hashlib, hmac, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > tolerance:
        return False

    expected = hmac.new(
        secret.encode(), f'{parts["t"]}.'.encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Reintentos

Una respuesta 2xx es una entrega buena; cualquier otra cosa, o un tiempo de espera de 10 segundos, es un fallo. El primer intento sale en el momento; si falla, se reintenta una hora después del fallo, y luego a las dos, a las cuatro y a las ocho horas del fallo anterior. Son cinco intentos en total: tras el quinto fallo la entrega queda agotada y puedes relanzarla a mano desde Ajustes → Integraciones → Webhooks. Las entregas agotadas aparecen en el informe diario interno de Alethexis.

Idempotencia

Alethexis-Event-Id identifica el evento, no el intento: un reintento repite el mismo identificador. Guarda los que ya has procesado y descarta los repetidos. Un mismo evento llega una vez a cada endpoint suscrito.

Catálogo v1

v1 tiene nueve eventos. Cada endpoint recibe solo los eventos a los que se suscribe.

Qué no viaja en un webhook

Las cargas llevan identificadores, estados y fechas. Nunca nombres, textos ni datos de personas. El detalle se lee después con la API. Hasta el 18 de septiembre de 2026 algunos eventos llevaban también el nombre del sistema o de la herramienta; ya no, porque ese nombre lo escribe tu organización y nada impide que contenga el de una persona.

Cómo obtener el detalle a partir de un webhook

Cada carga trae los identificadores necesarios para pedirle el resto a la API con tu clave. Del `system_id` de un evento cuelgan su clasificación, sus controles y sus evidencias:

# data.system_id from a system.created / system.reclassified payload
SYSTEM_ID="8f2c…"

curl -H "Authorization: Bearer $ALETHEXIS_API_KEY" \
  "https://www.alethexis.com/api/v1/classifications?system_id=$SYSTEM_ID&current=true"

curl -H "Authorization: Bearer $ALETHEXIS_API_KEY" \
  "https://www.alethexis.com/api/v1/controls?system_id=$SYSTEM_ID"

curl -H "Authorization: Bearer $ALETHEXIS_API_KEY" \
  "https://www.alethexis.com/api/v1/evidence?system_id=$SYSTEM_ID"

Los riesgos todavía no tienen recurso propio en la API: de `risk.high_registered` puedes resolver el sistema por su `system_id`, y el riesgo se consulta en la plataforma.

Requisitos del receptor

La URL tiene que ser https y resolver a una dirección pública: no se entregan webhooks a direcciones privadas ni internas. Responde en menos de 10 segundos; si necesitas más tiempo, acepta la entrega y procesa después.