Webhooks
The webhook deliverer streams audit events from the gateway to a destination URL of your choice. It is the integration surface for SIEM tooling (Datadog, Splunk, Sumo), incident pipelines (PagerDuty, Opsgenie), chat (Slack, Microsoft Teams via webhook bridges), and any internal service that wants to react to gateway state changes in real time.
The deliverer never blocks the originating request. The audit row is committed to durable storage as part of the request, and the delivery itself is enqueued and dispatched in the background. A dead destination cannot stall the gateway's hot path.
Event types
Four event types can be selected for a destination. Subscribe a destination to any subset of them. A destination only ever receives the events it explicitly subscribes to.
| Event | Fires when |
|---|---|
| api_key_revealed | The vault reveal endpoint returns an API key's plaintext value to an operator. Key reveals are temporarily unavailable (see the key vault), so expect no deliveries of this event until they return. |
| compression_threshold_breached | The optimizer's prompt compression falls below its configured floor for a request. |
| anomaly_detected | A request's thinking-token spend is flagged as anomalous against the team's recent usage. |
| session_thinking_governor_tripped | An agent session's cumulative extended-thinking spend crosses its per-session cap, and the governor forces the rest of that session's steps to run with thinking off. See agent sessions. |
Three more event names are not in the table. capability_override_set (an
operator writes a per-org capability alias override) and
capability_override_cleared (an operator deletes one, reverting that
capability to the global default) cannot be selected yet: adding either to a
destination's event list currently returns an error. The events themselves
are real and will deliver once that gap closes; there is no workaround on your
side in the meantime. reconciliation_variance is reserved: IQ is
bring-your-own-key only today, so this event does not fire for customers.
Six older event names -- request_completed, request_failed,
quota_exceeded, key_revoked, focus_mode_changed, and
alias_overridden -- are still accepted when you create a destination through
the API, but nothing in the gateway emits them, and the dashboard does not
offer them; a destination subscribed only to those will sit idle.
New events carry an event_id in the JSON body and the matching
X-IQ-Event-Id header. Use it to identify the event across retries;
X-IQ-Delivery-Id identifies the individual delivery attempt.
Setting up a destination
Settings → Webhooks → "Add destination". Required fields:
- URL. HTTPS only; the deliverer rejects HTTP destinations at create
time. The URL must resolve at create time to a non-private IP (no
127.0.0.1,10.*,192.168.*,169.254.*); the deliverer re-resolves at delivery time and rejects on a private-IP DNS rebind. - Secret. 32 random bytes rendered as a 64-character hex string (the dashboard generates one for you). The deliverer signs every payload with this secret and HMAC-SHA256; the receiver verifies the signature. Sign with the hex string exactly as issued, encoded as ASCII, rather than with the 32 bytes it decodes to.
- Events. A non-empty subset of the event-type list above. An empty subset is rejected at create time, so name every event you want; a destination never receives an event it did not subscribe to.
The dashboard surface lives at /settings#webhooks.
Wire format
A delivery is a single HTTPS POST with a JSON body and seven X-IQ-
headers for events with an event_id. X-IQ-Timestamp is Unix epoch seconds, not an ISO-8601 string:
POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-IQ-Event-Type: api_key_revealed
X-IQ-Event-Id: d0cbbd67-f62a-4b3d-98c7-86d352bba141
X-IQ-Delivery-Id: 8f14e45f-ceea-467a-9c33-1a2b3c4d5e6f
X-IQ-Attempt: 1
X-IQ-Timestamp: 1778437451
X-IQ-Signature: sha256=4c91...e2a3
X-IQ-Signature-V2: sha256=b07d...5c11
{
"event_id": "d0cbbd67-f62a-4b3d-98c7-86d352bba141",
"event_type": "api_key_revealed",
"org_id": "org_2bX3...",
"target_type": "api_key",
"target_id": "key_5fK1...",
"metadata": {
"prefix": "gw_live_9f2a1c4b",
"revealed_by": "user_a1b2...",
"encryption_version": 1,
"step_up": "webauthn"
}
}
The actor's email stays on the audit row; it is not part of the delivery body.
The body is JSON-canonicalised before signing (sorted keys, no extraneous whitespace) so a receiver that re-canonicalises and re-signs gets the same bytes.
Verifying the signature
The signature uses the timestamped construction:
HMAC-SHA256(secret, "{X-IQ-Timestamp}.{request_body}")
A receiver that does not check the timestamp is vulnerable to replay. Reject any delivery whose timestamp is more than five minutes off your clock.
A reference Python verifier:
import hmac
import hashlib
import time
def verify(secret: bytes, body: bytes, headers: dict[str, str]) -> bool:
timestamp = headers.get("X-IQ-Timestamp", "")
signature = headers.get("X-IQ-Signature", "")
if not signature.startswith("sha256="):
return False
sent = signature[len("sha256="):]
signed_payload = f"{timestamp}.".encode() + body
expected = hmac.new(secret, signed_payload, hashlib.sha256).hexdigest()
if not hmac.compare_digest(sent, expected):
return False
try:
skew = abs(time.time() - int(timestamp))
except ValueError:
return False
return skew <= 300
Use hmac.compare_digest (or your stack's equivalent constant-time
compare) so a timing side-channel cannot leak the signature byte by
byte.
X-IQ-Signature-V2 is an additional signature that also binds the
delivery id, attempt and event type. The check above is enough to
verify the payload.
Retry semantics
The deliverer waits up to 10 seconds for your endpoint to start responding, and gives each attempt at most 20 seconds in total, before treating it as a timeout. See /docs/operations/webhook-capacity-planning for sizing your receiver against the full delivery rate and retry ladder.
| Receiver response | Deliverer action |
|---|---|
| 2xx | Mark the delivery success. |
| 5xx | Reschedule: the attempt lands failed and a fresh pending row queues at the backoff. Backoff: 1s, 5s, 25s, then 125s for each remaining attempt. |
| Network error / TLS failure / timeout | Reschedule on the same backoff schedule. |
| Any 3xx or 4xx, 408 and 429 included | Mark failed with no follow-up attempt. The receiver's misconfiguration cannot self-resolve. |
| Attempt 5 still failing on a 5xx, a timeout, or a network error | Mark dead_lettered. |
Use Retry on the latest failed or dead_lettered attempt once its event
chain is no longer retrying and the destination is active. Retry enqueues
a fresh attempt-1 delivery with the same event_id and keeps the original
row in the log. When Retry is blocked, the delivery log shows the gateway's
reason. Use it after fixing the receiver.
Payload size
The envelope carries metadata rather than prompt or response content, so
payloads stay small: the largest event today, api_key_revealed, is a
few hundred bytes. Nothing is truncated on the way out and there is no
truncation flag on the wire, so a receiver does not need to branch on
one.
On the reply side, the deliverer keeps the first 4 KiB of your response body in the delivery log so a pathological receiver cannot blow up the deliveries view. That excerpt exists for your own debugging; it has no bearing on the delivery's status.
Test fire
Settings → Webhooks → row → "Test fire". The deliverer queues a synthetic
test_fire event for that one destination, sends it on its next poll,
and the result then appears in the delivery log. The test fire reaches
only the destination you
fired it from, it does not depend on that destination's event subset, and
the destination has to be active rather than paused.
Use it after any receiver-side change to confirm the signing and verification path still works end-to-end.
Delivery log
Settings → Webhooks → "View deliveries" opens a modal with the last 100 deliveries for that destination. Each row carries:
- The event type and the truncated delivery id.
- The destination response code (or "network error").
- The attempt number and the time of that attempt.
- A "Retry" button on failed and dead-lettered rows.
Each attempt is its own row, so a retried event appears once per attempt rather than as a single row with a rising counter.
The full delivery history is retained on the gateway side. The modal's last-100 cap is a UI choice; the data is not pruned.
Limits
There is no per-destination or per-org cap on delivery volume today, so a burst of events produces a burst of deliveries. What bounds the dispatch rate is the deliverer itself: it leases the deliveries that are due and dispatches them through a bounded worker pool that IQ manages. There is no knob for it on your side.
An org can hold up to 25 destinations. A create past that returns 409.
Deduplication
Your receiver may see the same event more than once. After verifying the
signature, use the body’s event_id to deduplicate events in your receiver.
Automatic and manual retries retain that event_id; each new attempt has
its own X-IQ-Delivery-Id. Store the event id with your processing result
and return a 2xx for an event you have already handled.
Older deliveries may lack an event_id and X-IQ-Event-Id. A manual retry
of an older delivery assigns an event id for subsequent retries; use your
own processing records to check whether you handled the original delivery.
Pausing a destination
Use Pause in Settings → Webhooks to stop deliveries to a destination. Events sent while paused are dropped for that destination, not queued for later delivery. Resume the destination before using Test fire or Retry.
Rollback
The deliverer can be disabled gateway-wide. When it is off, dispatch stops, no new deliveries enqueue, and the existing delivery history stays where it is. The dashboard's delivery-log modal still renders the historical rows. Re-enabling resumes from where the worker left off.
See also
- /docs/vault -- the
api_key_revealedevent source surface. - /docs/optimizer -- the
compression_threshold_breachedevent source surface. - /docs/sessions -- the
session_thinking_governor_trippedevent source surface. - /docs/capabilities -- the
capability_override_setandcapability_override_clearedevent source surface. - /docs/operations/webhook-capacity-planning -- size your receiver for the delivery rate and retry ladder.
- /audit -- the audit log shows the same events the webhook destinations receive, plus the deliveries-attempted column for cross-reference.