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.