Webhooks

Las cabeceras que enviamos

• Content-Type: application/json
• X-Ideaudit-Event — una de audit.finalized, audit.outcome.recorded, entity.created.
• X-Ideaudit-Signature: sha256=<hex> — mira abajo.
• X-Ideaudit-Endpoint: <uuid> — el id de tu endpoint, para enrutar en receptores con varios endpoints.

Verificar la firma (Node)

La firma es HMAC-SHA256(secret, raw_request_body) en hex, con el prefijo sha256=. Compárala contra los bytes crudos del cuerpo, nunca contra el JSON reserializado.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(secret: string, signatureHeader: string, rawBody: string): boolean {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(signatureHeader);
  const b = Buffer.from(expected);
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

Verificar la firma (Python)

import hmac, hashlib

def verify(secret: str, signature_header: str, raw_body: bytes) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Eventos de prueba

El botón «Probar» del dashboard usa el id de tu auditoría finalizada más reciente (o el UUID de ceros, si no tienes ninguna) y añade isTest: true al payload. Mira ese campo en tu receptor para saltarte los efectos secundarios.

Desactivación automática

Tras 5 respuestas seguidas fuera del rango 2xx ponemos active = false y marcamos el endpoint como desactivado. Arregla el receptor y pulsa Reactivar en Ajustes → Webhooks. El historial reciente de entregas — estado y cuerpo de la respuesta — se ve en un panel desplegable por endpoint.