Webhooks
SecureAI pode enviar eventos de segurança e de plataforma para seus próprios endpoints HTTP em tempo real – blocos Prompt Shield, vazamentos canário, incidentes DLP/PII, eventos de limite de API e failovers de modelo. Cada entrega é assinada com uma assinatura HMAC-SHA256 para que você possa verificar se ela veio da SecureAI e não foi adulterada ou reproduzida. Os endpoints do Webhook são gerenciados por administradores em Admin → Webhooks (API base/api/admin/webhooks).
Gerenciando terminais
Entradas de tempo de criação:
url, description, events[] (consulte Eventos) e enabled. O segredo de assinatura (whsec_...) é mostrado apenas na criação e rotação — armazene-o com segurança; você não pode recuperá-lo novamente.
O endpoint url é validado por SSRF: apenas http(s) é aceito e hosts privados/loopback/link-local são rejeitados, a menos que a instância seja executada com WEBHOOKS_ALLOW_PRIVATE=true (receptores auto-hospedados geralmente precisam disso).
Formato de entrega
Cada entrega é um HTTPPOST com um corpo JSON:
Seu endpoint deve retornar qualquer status
2xx para confirmar a entrega.
Verificando a assinatura
Recalcule o 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á fora de sua janela de tolerância (proteção de reprodução). Verifique o corpo da solicitação bruta — analisar e serializar novamente o JSON primeiro alterará os bytes e quebrará a assinatura.
Node.js (Expresso)
Python (frasco)
Confiabilidade
- Tentativas: até 3 tentativas com espera de 0s/10s/60s, tempo limite de 5s cada. Qualquer
2xxreconhece. - Desativação automática: após 20 falhas consecutivas de entrega, um endpoint é desativado automaticamente; um administrador o reativa (o que também redefine o contador de falhas).
- Pelo menos uma vez: as entregas podem ser repetidas — desduplicação em
X-SecureAI-Delivery(ou na carga útilid). - Dispare e esqueça: a entrega do webhook nunca bloqueia ou atrasa a solicitação de API de origem.
Relacionado
- Webhook Events — o catálogo completo de eventos e cargas úteis.
- Redundância e Failover — fonte de
api:model_failover. - Threat Defense — fonte dos eventos
promptshield:*.

