Webhooks & Events

run.started

Overview

Fired when orchestration begins dispatching cases to execution agents.

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

Step-by-step procedure

Subscribe

Include "run.started" 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": "run.started",
  "created": "2026-05-20T12:00:00Z",
  "data": {
    "object": {
      "id": "resource_id",
      "organization_id": "org_abc",
      "run_id": "run_xyz"
    }
  }
}

Was this page helpful?