Skip to content
IQ

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_revealed event source surface.
  • /docs/optimizer -- the compression_threshold_breached event source surface.
  • /docs/sessions -- the session_thinking_governor_tripped event source surface.
  • /docs/capabilities -- the capability_override_set and capability_override_cleared event 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.