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

Browse docs

On this page

01 Delivery payload

details

POST body fields

Each delivery POSTs JSON with id, event_type, workspace_id, occurred_at, data, and delivery_attempt. Test deliveries from POST .../test also set test: true. This is not the realtime Events envelope (which uses type and has no delivery_attempt). Headers are x-agentops-event, x-agentops-timestamp (Unix seconds), and x-agentops-signature (HMAC-SHA256).

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 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

Published webhook events

Subscriptions can specify individual event types or use wildcard *. Realtime.Events always fans matching publishes into webhook delivery. Shipped types include command lifecycle; trace.created, trace.event.appended, and trace.finalized; replay started/updated/completed/failed/stuck_detected; approval_request created/decided/executed; eval_run.completed; fleet lifecycle plus fleet.batch_operation.created/progress/completed; failure_group.created; webhook.test; security.violation.created, security.violation.resolved, and security.report.generated; and gateway.frozen / gateway.thawed.

failure_group.anomaly_detected is not a webhook event

That string is an alert-rule trigger. When it fires the platform publishes alert.created to destinations. The webhook and realtime event for a new group is failure_group.created (failure_group_id, trace_id, signature, severity).

05 Operator console

details

/app/admin

Workspace admin creates subscriptions, reveals the signing secret once, sends a test delivery (event_type webhook.test, test true), lists recent attempts, filters failed rows, and retries. There is no separate webhooks settings screen.

Related docs