Batches

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.

postWebhookbatchWorkflowEvent

Payload

attemptinteger required

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

contextunknown
event'start' | 'results' | 'wait' required

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.

event_idstring required

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.

record_idstring required

The record's custom_id.

stepinteger required

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

workflow_idstring required

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

Response

The callback's answer.

errorstring

For failed: why the record failed, required and not blank. The record's error line carries it as the message, trimmed and cut to 1000 bytes.

outputobject

For completed: the record's result body, a JSON object (null is not one). OpenRelay sets its usage key to the record's prompt_tokens, completion_tokens and total_tokens, summed over its requests, replacing any usage the object carries.

retry_after_msinteger

For wait: the pause before the wait event, in milliseconds. Omitted, 0 or negative waits 1000; a value over 60000 waits 60000.

state'continue' | 'wait' | 'completed' | 'failed'

continue (also when state is omitted): run requests, then send a results event. wait: pause for retry_after_ms, then send a wait event. completed: the record succeeds with output as its result body. failed: the record fails with workflow_failed. Each continue or wait answer is one step of max_steps.

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.