Webhooks

Async terminal callbacks

Async runs can call your backend when execution reaches a terminal state.

curl -X POST https://developer.creao.ai/v1/runs \
  -H "Authorization: Bearer cr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "00000000-0000-4000-8000-000000000000",
    "input": { "query": "Create a weekly sales summary" },
    "webhook_url": "https://your-server.example/webhooks/creao"
  }'

Webhook URLs must be public http or https URLs. Localhost, private network, link-local, and metadata-service targets are rejected or skipped.

Payload

Webhook payloads include the run, conversation, model, terminal status, and either result or error.

{
  "runId": "11111111-1111-4111-8111-111111111111",
  "status": "completed",
  "threadId": "22222222-2222-4222-8222-222222222222",
  "conversationId": "22222222-2222-4222-8222-222222222222",
  "model": "anthropic/claude-haiku-4-5",
  "result": {
    "text": "Done."
  }
}

Use conversationId as the public conversation identifier. threadId is included in the current payload for compatibility and has the same value for CREAO CLI conversations. Failed run example:

{
  "runId": "11111111-1111-4111-8111-111111111111",
  "status": "failed",
  "threadId": "22222222-2222-4222-8222-222222222222",
  "conversationId": "22222222-2222-4222-8222-222222222222",
  "model": "anthropic/claude-haiku-4-5",
  "error": {
    "code": "EXECUTION_FAILED",
    "message": "Agent execution failed"
  }
}

Delivery behavior

CREAO makes up to three delivery attempts with short backoff. A non-2xx response, a connection error, or no response within 10 seconds is retried. Redirects are not followed, so a 3xx response counts as a failed attempt. The first 2xx response ends delivery, marks the webhook as delivered, and sets webhook_delivered_at on the run object. Every request carries these headers:

Header	Value
`Content-Type`	`application/json`
`X-Creao-Delivery-Id`	A UUID that is the same on every attempt for the run’s result

Delivery is at least once: a retry can repeat a request your endpoint already processed, for example when it timed out before responding. Design webhook handlers to be idempotent and deduplicate on X-Creao-Delivery-Id (or runId). Respond with a 2xx quickly and do slow work afterwards.

Polling fallback

Webhooks are best-effort delivery. Your backend can always poll:

curl https://developer.creao.ai/v1/runs/11111111-1111-4111-8111-111111111111 \
  -H "Authorization: Bearer cr_sk_your_key_here"

Get Started

Agents

Agent Memory

Agent Files

Product Profile

Agent Runs

Super Agent

Account

Workspaces

Workspace Files

Secrets

Skills

Concepts

Async terminal callbacks

Payload

Delivery behavior

Polling fallback

​Async terminal callbacks

​Payload

​Delivery behavior

​Polling fallback

Async terminal callbacks

Payload

Delivery behavior

Polling fallback