Skip to main content

Webhooks

SecureAI puede enviar eventos de plataforma y seguridad a sus propios endpoints HTTP en tiempo real: bloqueos de Prompt Shield, fugas canarias, incidentes DLP/PII, eventos de límite de API y conmutaciones por error de modelos. Cada entrega está firmada con una firma HMAC-SHA256 para que pueda verificar que proviene de SecureAI y que no fue manipulada ni reproducida. Los administradores administran los endpoints de Webhook en Admin → Webhooks (base de API /api/admin/webhooks).

Gestión de endpoints

Entradas en el momento de la creación: url, description, events[] (consulte Eventos) y enabled. El secreto de firma (whsec_...) se muestra solo al crear y rotar; guárdelo de forma segura; no puedes recuperarlo de nuevo. El endpoint url está validado por SSRF: solo se acepta http(s) y los hosts privados/loopback/link-local se rechazan a menos que la instancia se ejecute con WEBHOOKS_ALLOW_PRIVATE=true (los receptores autohospedados a menudo necesitan esto).

Formato de entrega

Cada entrega es un HTTP POST con un cuerpo JSON:
Y estos encabezados: Su endpoint debe devolver cualquier estado 2xx para acusar recibo de la entrega.

Verificando la firma

Vuelva a calcular el HMAC sobre `${t}.${rawBody}` using your signing secret and compare it to the v1 value. Reject the delivery if it doesn’t match, or if t está fuera de su ventana de tolerancia (protección de reproducción). Verifique con el cuerpo de la solicitud sin formato: analizar y volver a serializar el JSON primero cambiará los bytes y romperá la firma.

Node.js (Rápido)

Python (frasco)

Confiabilidad

  • Reintentos: hasta 3 intentos con retroceso de 0 s/10 s/60 s, tiempo de espera de 5 s cada uno. Cualquier 2xx reconoce.
  • Desactivación automática: después de 20 errores de entrega consecutivos, un endpoint se desactiva automáticamente; un administrador lo vuelve a habilitar (lo que también restablece el contador de fallas).
  • Al menos una vez: las entregas pueden repetirse: deduplicar en X-SecureAI-Delivery (o la carga útil id).
  • Dispara y olvida: la entrega del webhook nunca bloquea ni retrasa la solicitud de API de origen.

Relacionado