Webhooks & Events

agent.offline

Overview

Fired when an execution agent misses heartbeat thresholds.

Payloads are signed with HMAC-SHA256 using your webhook secret. Verify signatures before processing.

Step-by-step procedure

Subscribe

Include "agent.offline" in webhook events array at registration.

Use Admin Center or POST /v1/webhooks.

Verify delivery

Validate HMAC-SHA256 signature header against raw request body.

Return HTTP 200 within 10 seconds; queue heavy work asynchronously.

Handle idempotently

Store event id; ignore duplicate deliveries with same id.

Reconcile with Console state if payload and UI disagree.

Best practices

  • Respond with 2xx within 10 seconds; process asynchronously
  • Store event id for idempotent handling
  • Rotate webhook secrets periodically from Admin Center

Example payload envelope

{
  "id": "evt_abc123",
  "type": "agent.offline",
  "created": "2026-05-20T12:00:00Z",
  "data": {
    "object": {
      "id": "resource_id",
      "organization_id": "org_abc",
      "run_id": "run_xyz"
    }
  }
}

Was this page helpful?