Skip to main content

Async terminal callbacks

Async runs can call your backend when execution reaches a terminal state.
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.
Use conversationId as the public conversation identifier. threadId is included in the current payload for compatibility and has the same value for Developer API conversations. Failed run example:

Delivery behavior

CREAO retries delivery with short backoff. A 2xx response marks the webhook as delivered and sets webhook_delivered_at on the run object. Design webhook handlers to be idempotent. Use runId as your deduplication key.

Polling fallback

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