Webhooks & Events

Platforms in the opensecstack ecosystem communicate through signed, replay-protected webhooks rather than ad-hoc HTTP calls. Every webhook uses the same HMAC-SHA256 signing scheme, a ±5-minute replay window, and per-source shared secrets. This page is the cross-platform reference — consult the individual platform docs for endpoint-specific details.

Overview

Two platforms act as primary webhook receivers in the ecosystem:

• IRFlow — receives events from APIGuard, CITADEL, and ThreatFlow to create or enrich incidents automatically.
• ThreatFlow — receives events from APIGuard, CITADEL, and generic external sources; pushes outbound events to IRFlow, NIS2Compass, and OpenCSIRT.

All webhook endpoints share one signing scheme that differs only in the header names and per-source secret used. No JWT is required — authentication is entirely via HMAC.

Wire format & signing

Every signed webhook request carries two mandatory headers. The canonical signing input is the Unix timestamp, a literal dot, and the raw request body — exactly as received on the wire, with no re-serialisation or whitespace normalisation.

The canonical signing formula used by both platforms is:

signed_payload = timestamp + "." + raw_body
signature      = hex(HMAC-SHA256(per_source_secret, signed_payload))
header_value   = "sha256=" + signature

Replay protection

Both IRFlow and ThreatFlow reject requests whose timestamp falls outside a ±5-minute window of the server's current time. IRFlow exposes the tolerance via the environment variable IRFLOW_WEBHOOK_CLOCK_SKEW_TOLERANCE (default 5m); ThreatFlow hard-codes maxTimestampSkew = 300 seconds.

The ±5-minute window balances capture-replay risk against real-world NTP drift between peers. A tighter window (e.g. 30 s) is possible but requires well-synchronised clocks across all sender platforms. Requests outside the window return 401 with a structured JSON error body.

ThreatFlow also issues a unique X-ThreatFlow-Delivery header (UUID v4) per delivery. Receivers should use this ID to deduplicate retried deliveries. IRFlow logs the optional X-Irflow-Event-Id for the same purpose; v1.1 will persist and reject duplicate IDs.

Per-source secrets

Each source platform has its own shared secret. Never reuse a secret across sources. Secrets are configured on the receiver side. If a per-source secret is not set, the corresponding endpoint returns 503 until configured — this is fail-closed by design.

Signed-webhook example

The following shows a complete IRFlow inbound webhook from ThreatFlow — a correlation match payload with the signing headers already populated. The same shape applies to APIGuard and CITADEL payloads with their respective event types.

"cm"># Signed webhook from ThreatFlow -> IRFlow
"cm"># Headers
X-Irflow-Timestamp: 1745056462
X-Irflow-Signature: sha256=3a7f1c84e2d09b56f8ac4210edb3f70a92651cc8fa2e47d13b09e5a7c682b41f
X-Irflow-Event-Id: tf-bundle-0000042
Content-Type: application/json

"cm"># Body
{
  "event_id":   "tf-bundle-0000042",
  "event_type": "threatflow.bundle.published",
  "bundle_id":  "tf_bundle_789",
  "incident_id": "inc_123",
  "iocs": [
    {"type": "ipv4",   "value": "203.0.113.5",       "confidence": 0.92},
    {"type": "sha256", "value": "abc123...",          "confidence": 0.81},
    {"type": "domain", "value": "malicious.example", "confidence": 0.77}
  ],
  "occurred_at": "2026-04-19T10:14:22Z"
}

"cm"># Signature computation (pseudo-code):
"cm"># signed_payload = "1745056462" + "." + raw_body_bytes
"cm"># signature      = hex(HMAC-SHA256(IRFLOW_WEBHOOK_THREATFLOW_SECRET, signed_payload))
"cm"># header         = "sha256=" + signature

The SDK ships pre-built sender clients that handle signing automatically — prefer those over rolling your own implementation.

Event & contract types

The SDK defines a typed Event envelope that all platforms share. The common fields are event_id, event_type, source, ts_utc, and an optional project_id, with a payload map carrying event-specific data.

Error responses

Both platforms return structured JSON errors: {"error": "human-readable description"}.

Retry & dead-letter (ThreatFlow)

When an outbound delivery from ThreatFlow fails, it retries with exponential backoff. After all attempts are exhausted, the delivery moves to a dead-letter queue for manual inspection and replay.

401, 403, and 404 responses are non-retryable — retrying will not change the outcome. Network errors, timeouts, and 5xx responses are retried. Dead-letter items are retained for 30 days (configurable) and can be replayed via the ThreatFlow admin API.