Saltar a contenido

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.