Skip to content
OpenRelay is in early access, and the /v1 API is stable. New capabilities ship in the changelog.
Skip to Content
GuidesInference APIsAsync API

Delivery webhooks

Get an async job's results pushed to your endpoint when it ends, with the three async.job events, the payload, signing and retries.

Async is in beta

Shapes and limits can still change before general availability.

Instead of polling, subscribe a webhook to the event of a job ending. It is sent once per job, to each enabled webhook that lists it:

EventWhen
async.job.completedThe job ended with every request at an outcome. A job whose deadline passed ends completed, with its unstarted requests counted expired, so there is no expired event.
async.job.cancelledThe job ended cancelled.
async.job.failedThe job failed: its input could not be read.

There are no per-request events.

Subscribe

Add the events in the dashboard (Settings, Integrations, Webhooks, under Async jobs) or through the API:

curl -X POST https://api.openrelay.inc/v1/orgs/$ORG_ID/webhooks/create \
  -H "Authorization: Bearer $OPENRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "async-done",
    "url": "https://example.com/hooks/openrelay",
    "events": ["async.job.completed", "async.job.failed"]
  }'

Listing an async job event needs the Batch: Read permission as well as Integrations: Write. The general webhook setup, the signing secret and signature verification are in the Webhooks guide.

The payload

{
  "id": "evt_…",
  "type": "async.job.completed",
  "created_at": "2026-11-04T12:01:40Z",
  "data": {
    "job": {"id": "ajob_01JB7ZK3M2X8Q4V", "object": "async.job", "status": "completed", "request_counts": {}, "metadata": {}},
    "results": [{"custom_id": "ticket-T-123", "status": "completed", "response": {}, "cost_nano_usd": 397280}],
    "results_url": null
  }
}
  • data.job is the job exactly as GET /v1/async/jobs/{id} answers it.
  • Small jobs carry their results. When the results come to 256 KiB or less and the create rejected no line, data.results holds every result and data.results_url is null. That covers a job of one: the response itself is pushed to you.
  • Larger jobs carry a link. Otherwise data.results is null and data.results_url is the job's results pages, read with an API key that can read Async.
  • The event id is derived from the event type and the job, so a job's event always has the same id. Dedupe on it.

Signing and retries

Every delivery is signed in X-OpenRelay-Signature like any other webhook; verify it on the raw body. A delivery that fails is retried 7 times, after 10 seconds, 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 15 hours, the last about 23.6 hours after the first. Delivery is at least once.

Each attempt rebuilds the body, so a job's results can ride inline on a retry even when the first attempt carried a link. Polling GET /v1/async/jobs/{id} always works too.

The field-by-field reference is Async job events.

On this page