Skip to content

Signed webhooks

Register an HTTPS endpoint under Settings › Alerts and monitoring › Alert Routing › Webhooks to receive your tenant's events (risk-score changes, critical CVEs, detected breaches, and others according to your routing rules) in near real time, instead of having to poll us.

flowchart LR
    S[Vendor SBOM<br/>or own asset] --> M["Match against CVEs<br/>(matchComponentsWithLocalCache)"]
    M --> I{"Alertable?<br/>(isAlertableCve)"}
    I -->|yes| P["Alert pipeline<br/>(runCveAlertPipeline)"]
    I -->|no| Z[No alert]
    P --> R{Tenant's<br/>routing rule}
    R --> W[Signed delivery<br/>to the webhook]
    R --> N[Notification<br/>Slack / Teams / email / PagerDuty]

SBOM → CVE → alert → notification chain. Destinations are configured as described in Getting started. The webhook delivery's signature is the next section.

Verifying the signature

Every delivery includes four headers:

Header Content
X-HodeiShield-Timestamp Timestamp in seconds, different on every attempt
X-HodeiShield-Signature-256 sha256= + HMAC-SHA256(secret, "{timestamp}.{body}")
X-HodeiShield-Delivery Identical across every retry of one delivery — use it to deduplicate
X-HodeiShield-Event Event type

The secret (whsec_…) is shown once when you create the webhook; if you lose it, rotate it — it cannot be recovered. Always verify the signature before processing the body, and reject timestamps older than a few minutes to prevent replay attacks.

import hashlib
import hmac
import time

def is_valid(secret: str, timestamp: str, body: bytes, received_signature: str,
             tolerance: int = 300) -> bool:
    # Reject stale (or far-future) deliveries first: a captured request stays
    # correctly signed forever, so freshness is the only replay defence.
    try:
        sent_at = int(timestamp)
    except ValueError:
        return False
    if abs(time.time() - sent_at) > tolerance:
        return False
    message = f"{timestamp}.".encode() + body
    expected = "sha256=" + hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received_signature)

Retries

If your endpoint doesn't respond 2xx, we make up to six attempts in all: the first at dispatch, then five retries after 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours. Once the six attempts are exhausted, the delivery is marked failed and visible in the console, where you can requeue it manually.

This schedule applies to the Webhook destination (the HTTPS endpoint of your own system) and to the Sekoia.io intake. The other destinations (Slack, Teams, Jira, ServiceNow, PagerDuty, OpsGenie, SIEM and e-mail) do not retry on their own: they make a single attempt and, if it fails, the delivery is marked failed and you can retry it manually from the console (up to three times). Because a retry can deliver the same event twice, deduplicate on X-HodeiShield-Delivery.

If signature verification fails, see Troubleshooting.

Migrating from the legacy signature

Older webhooks use a signature without a timestamp (X-HodeiShield-Signature, an HMAC of the body with no replay protection). If your integration still uses it, migrate to X-HodeiShield-Signature-256: the legacy signature will be retired and stop being sent. While it is still active, the delivery also carries that legacy header as a fifth header, in addition to the four in the table above.