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

Workflow record callback

The events OpenRelay POSTs to a workflow record's callback, and the answers it accepts: the next requests to run, a pause, or the outcome. A workflow record is a batch record whose body carries openrelay.workflow. OpenRelay POSTs an event to its workflow.url, runs the requests the answer returns, and POSTs their results as the next event, until the callback answers completed or failed. The URL is the record's own, not a registered webhook. The request carries the record's workflow.authorization value verbatim as its Authorization header, and Content-Type application/json; it is not signed. Each event is delivered up to four times, with pauses of 1, 2 and 3 seconds between attempts and each attempt bounded by callback_timeout_ms. A timeout, a connection error, a 429 or a 5xx answer is retried, and so is a redirect, which is never followed. When all four attempts fail, the record fails with workflow_callback_unreachable and the rest of the batch keeps running. Any other non-2xx answer fails the record with workflow_callback_rejected.

Request Body

application/json
  1. body

One event OpenRelay POSTs to a workflow record's workflow.url, with the record's workflow.authorization value as the Authorization header. A serialized event is at most 2 MiB (2097152 bytes), context and results included; when a step's results would make it larger, the event is not sent and the record fails with workflow_invalid_response, with the requests that ran still billed.

event_id*string

Deterministic id of this event. A retried delivery, or the same event sent again after a batch worker resumes the record from its last saved step, carries the same event_id, so key your state on it and give a repeated event the same answer.

Match^wf_evt_[0-9a-f]{32}$
event*string

start is the record's first event. results follows a continue answer: every request of that step finished, and results holds their outcomes. wait follows a wait answer, once the pause is over.

Value in"start""results""wait"
workflow_id*string

The batch id and the record's custom_id, joined as <batch_id>:<custom_id>.

record_id*string

The record's custom_id.

step*integer

Callback answers of continue or wait consumed so far, starting at 0.

Range0 <= value
attempt*integer

Always step + 1. It does not count deliveries: a retried delivery of an event carries the same attempt.

Range1 <= value
context?unknown

The record's workflow.context, unchanged. Absent when the record sets none.

results?array<>

On a results event: one entry per request of the previous step, in the order the answer returned them. Absent on start and wait events.

Response Body

Retried, as one of the event's four delivery attempts.

Example Requests
POST/batchWorkflowEvent

One event OpenRelay POSTs to a workflow record's workflow.url, with the record's workflow.authorization value as the Authorization header. A serialized event is at most 2 MiB (2097152 bytes), context and results included; when a step's results would make it larger, the event is not sent and the record fails with workflow_invalid_response, with the requests that ran still billed.

Request Body
application/json
{  "event_id": "wf_evt_8b2e4f6a1c3d5e7f9a0b2c4d6e8f0a1b",  "event": "results",  "workflow_id": "batch_9f8e7d6c5b4a:contract-42",  "record_id": "contract-42",  "step": 1,  "attempt": 2,  "context": {    "contractId": "contract-42"  },  "results": [    {      "id": "payment",      "stage_id": "payment",      "attempt": 1,      "custom_id": "payment",      "status_code": 200,      "body": {        "choices": [          {            "message": {              "content": "Net 30."            }          }        ]      },      "usage": {        "input_tokens": 11820,        "output_tokens": 140      }    }  ]}