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.

Platform docs

Error responses Rate limits Pagination Webhooks Authentication Versioning Idempotency Billing plans Billing flows

Details

Delivery payload

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.

Code example

Signature verification

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)

Details

Retry strategy

Exponential backoff

Backoff formula: 30 * 2^(attempt - 1) seconds. Maximum backoff: 1800 seconds (30 minutes). Maximum attempts: 8. Retry schedule: 30s, 60s, 120s, 240s, 480s, 960s, 1800s, 1800s. After 8 failed attempts, the delivery is marked as failed with no further retries.

Details

Event types

Available events

Subscriptions can specify individual event types or use the wildcard * to receive all events. Event types include command.complete, command.fail, trace.created, trace.finalized, replay.started, replay.completed, replay.failed, approval_request.created, approval_request.decided, robot.status_change, mission.status_update, fleet_alert.created, and more.

Related docs

Errors

Error format for webhook delivery failures

Authentication

Signing secrets and credential management

Operator - Webhooks

Webhook subscription API endpoints