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:
| Event | When |
|---|---|
async.job.completed | The 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.cancelled | The job ended cancelled. |
async.job.failed | The 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.jobis the job exactly asGET /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.resultsholds every result anddata.results_urlisnull. That covers a job of one: the response itself is pushed to you. - Larger jobs carry a link. Otherwise
data.resultsisnullanddata.results_urlis the job's results pages, read with an API key that can read Async. - The event
idis 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.
Results
The shape of an async result, how to page through the results of a job while it runs and after it ends, and why there is no output file.
Agents
What an async request can do for an agent today. Tool calls come back for your own loop; OpenRelay-run tool loops and workflows are not available in Async.