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 HTTPPOST con un cuerpo JSON:
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
2xxreconoce. - 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 útilid). - Dispara y olvida: la entrega del webhook nunca bloquea ni retrasa la solicitud de API de origen.
Relacionado
- Eventos Webhook: el catálogo completo de eventos y las cargas útiles.
- Redundancia y conmutación por error — fuente de
api:model_failover. - Threat Defense — fuente de los eventos
promptshield:*.

