Webhooks firmados¶
Registra un endpoint HTTPS en Configuración › Alertas y vigilancia › Enrutamiento de alertas › Webhooks para recibir eventos de tu inquilino (cambios de puntuación de riesgo, CVEs críticas, brechas detectadas, y otros según tus reglas de enrutado) en tiempo casi real, en lugar de tener que consultarnos.
flowchart LR
S[SBOM del proveedor<br/>o activo propio] --> M["Cruce con CVEs<br/>(matchComponentsWithLocalCache)"]
M --> I{"¿Es alertable?<br/>(isAlertableCve)"}
I -->|sí| P["Pipeline de alertas<br/>(runCveAlertPipeline)"]
I -->|no| Z[Sin alerta]
P --> R{Regla de enrutado<br/>del inquilino}
R --> W[Entrega firmada<br/>al webhook]
R --> N[Notificación<br/>Slack / Teams / correo / PagerDuty]
Cadena SBOM → CVE → alerta → notificación. Los destinos se configuran como se explica en Primeros pasos. La firma de la entrega al webhook es la sección siguiente.
Verificar la firma¶
Cada entrega incluye cuatro cabeceras:
| Cabecera | Contenido |
|---|---|
X-HodeiShield-Timestamp |
Marca de tiempo en segundos, distinta en cada intento |
X-HodeiShield-Signature-256 |
sha256= + HMAC-SHA256(secreto, "{timestamp}.{cuerpo}") |
X-HodeiShield-Delivery |
Idéntica en todos los reintentos de una misma entrega — úsala para deduplicar |
X-HodeiShield-Event |
Tipo de evento |
El secreto (whsec_…) se muestra una sola vez al crear el webhook; si lo pierdes, rótalo
— no se puede recuperar. Verifica siempre la firma antes de procesar el cuerpo, y rechaza
marcas de tiempo con más de unos minutos de antigüedad para evitar ataques de repetición.
import hashlib
import hmac
import time
def es_valida(secreto: str, timestamp: str, cuerpo: bytes, firma_recibida: str,
tolerancia: int = 300) -> bool:
# Rechaza primero las entregas antiguas (o del futuro): una petición
# capturada sigue bien firmada para siempre, así que la frescura es la
# única defensa contra la repetición.
try:
enviada = int(timestamp)
except ValueError:
return False
if abs(time.time() - enviada) > tolerancia:
return False
mensaje = f"{timestamp}.".encode() + cuerpo
esperada = "sha256=" + hmac.new(secreto.encode(), mensaje, hashlib.sha256).hexdigest()
return hmac.compare_digest(esperada, firma_recibida)
Reintentos¶
Si tu endpoint no responde 2xx, hacemos hasta seis intentos en total: el primero al emitir la entrega y
después cinco reintentos a los 5 minutos, 30 minutos, 2 horas, 6 horas y 24 horas. Agotados los seis intentos, la entrega queda marcada como fallida y visible
en la consola, donde puedes reencolarla manualmente.
Este calendario se aplica al destino Webhook (el endpoint HTTPS de tu propio sistema) y a
la entrada de Sekoia.io. Los demás destinos (Slack, Teams, Jira, ServiceNow, PagerDuty,
OpsGenie, SIEM y correo) no reintentan solos: hacen un único intento y, si falla, la entrega
queda marcada como fallida y puedes reintentarla manualmente desde la consola (hasta tres veces).
Como un reintento puede entregar el mismo evento dos veces, deduplica por
X-HodeiShield-Delivery.
Si la verificación de la firma falla, consulta Resolución de problemas.
Migración desde la firma heredada¶
Los webhooks antiguos usan una firma sin marca de tiempo
(X-HodeiShield-Signature, HMAC del cuerpo sin protección contra repetición). Si tu
integración todavía la usa, migra a X-HodeiShield-Signature-256: la firma heredada se
retirará y dejará de enviarse. Mientras siga activa, la entrega lleva además esa cabecera
heredada, como quinta cabecera, además de las cuatro de la tabla anterior.