Platform / Platform

Webhook delivery, signing, and retries

When an event matching a webhook subscription's event_types is published, the platform delivers an HTTP POST to the subscription URL.

API docs

01 Delivery payload

details

Event envelope

Each delivery sends a JSON body with the event envelope. The data field contains the event-specific payload (command, trace, alert, etc.). Deliveries include x-agentops-event (event type), x-agentops-timestamp (Unix timestamp), and x-agentops-signature (HMAC-SHA256 signature) headers.

02 Signature verification

example

HMAC-SHA256

1) Concatenate the timestamp and raw JSON body with a period: <timestamp>.<body>. 2) Compute HMAC-SHA256 using the subscription's signing secret as the key. 3) Hex-encode the result (lowercase). Always use constant-time comparison to prevent timing attacks.

python

# Python example
import hmac, hashlib

def verify_signature(timestamp, body, secret, signature):
    message = f"{timestamp}.{body}"
    expected = hmac.new(
        secret.encode(), message.encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

03 Retry strategy

details

Exponential backoff

Transport failures and HTTP 408, 425, 429, or 5xx responses retry with 30 * 2^(attempt - 1) second backoff, capped at 30 minutes and 8 attempts. Other 4xx responses, blocked outbound URLs, and invalid signing secrets fail without retry. Automatic redirects are disabled.

04 Event types

details

Available events

Subscriptions can specify individual event types or use wildcard *. Current events include command lifecycle, trace.created/event.appended/finalized, replay started/updated/completed/failed/stuck_detected, approval_request created/decided/executed, eval_run.completed, fleet lifecycle events, and failure_group.anomaly_detected.

Related docs