Set up an event-ingest workflow and check batch status

Event ingest is how a system hands Returning.AI a batch of rows and lets a workflow run once for each accepted batch. The API builds and checks the workflow; the batch's own lifecycle is read through the public event ingest status endpoint.

This page combines the two questions that always arrive together: "is my workflow configured for my envelope?" and "did my batch go through?".

The envelope contract

A sender posts a JSON envelope with three things: the trigger id at the root, the batch id at the root path the trigger is configured for, and an array of rows, each carrying the record id fields the trigger names.

{
  "trigger_id": "<PRODUCTION_TRIGGER_ID>",
  "metadata": { "batch_id": "net-deposit-20260710-001" },
  "data": [
    { "occurred_at": "2026-07-10T12:21:24.001Z", "event_type": "net_deposit.snapshot", "client_id": "<broker-client-id>", "deposit_id": "18774", "net_deposit_delta": 10000 }
  ]
}

That example shows only the event shape a batch carries. It is not a Workflow Builder API request; the batch goes to the event ingest endpoint your account was given, not to the base URL on these pages.

1. Create the workflow with the ingest trigger

Readback: the trigger's _id and its stored options. The _id is the value the sender posts as trigger_id.

To change the paths later, replace the trigger:

2. Understand the two deduplication layers

The batch id identifies one submission. The same batch id again is skipped before any row is checked, so an exact retry is always safe and always pays nothing.

A record id identifies one row. A record id seen before is skipped even inside a different batch, and other new rows in that batch still run.

Multiple record id paths are independent checks, not a combined key: a repeat of any one of them makes the row a duplicate, and the path name is not part of the identity. If one business record needs several fields, build one namespaced value before sending it, for example server-2:account-88:trade-100, and configure that single path.

A row with no value at any configured record id path is counted as missing and skipped.

3. Route the rows to the right step, then validate

Take every field key from the catalog rather than guessing one: GET /catalog returns platformActionFields.get and platformActionFields.post, each entry carrying the key the step stores, the label the platform stores beside it, and whether the field is builtin or custom.

The trigger's rows are in data. Map the array, not the envelope, unless a step needs the envelope itself. A workflow that fans out per row belongs in a row-level step; a workflow that needs one aggregate belongs in a bulk step.

Then validate and dry-run with a sample envelope:

Readback: the trace resolves the row from the seeded payload. A literal expression in the trace means the binding is wrong; see the binding playbook.

4. Deploy, then read a batch's status

After the sender posts a batch, three surfaces answer three different questions:

Surface	Question	Where
Event ingest status	Did the platform receive this batch, and did the workflow run it?	`GET /v1/data-workflows/event-ingests/status?trigger_id=<triggerId>&batch_id=<batchId>`
Bulk update callback	Did the resulting user update finish, and how many rows succeeded?	A URL the broker controls, configured on the bulk step
Failure webhook	Did a run end in error?	The workflow's `outgoingWebhookUrl`

The status read needs a community API key with the dataWorkflows permission. It is a separate permission from workflowBuilder, and it is the one place dataWorkflows still applies.

Meanings that matter:

pending or queued: accepted, waiting. Minutes of wait are normal for a scheduled dispatch.

processed: the workflow ran. It does not mean every step succeeded, and it does not mean balances changed.

skipped: a duplicate batch id, or every row was a duplicate or had no record id.

failed: rejected before running, for example a batch id missing from the configured path.

orphaned: no deployed workflow matched the trigger.

Read the run's own result with GET /{workflowId}/runs when you need to know whether steps succeeded. processed and a run error can both be true.

Read the newest status before an exact retry: a retry shows as skipped, which hides the original result.

5. Prove the batch end to end

GET /{workflowId}/runs for the run and GET /runs/{runId} for the step results.

For a bulk step, the bulk update job: status, then per-row details.

The member's own field value.

Your own ledger, to confirm you acknowledged the batch once.

A 2xx from the sender's post proves only that the request was accepted. An ingest row proves it was routed. A run proves it executed. Only the member's value proves the reward.

6. Failure handling

What you see	What it means	What to do
Ingest `failed` with a batch id path message	The batch id was not at the configured root path	Fix the sender, resend under a new batch id.
Ingest `skipped`	Duplicate batch, or all rows duplicated	Nothing to do unless the data is genuinely new.
Ingest `processed`, run `error`	The workflow ran and a step failed	Read the run detail, fix the step.
Status read `404` right after a `2xx` ingest	The batch id could not be read, so the row cannot be found by that id	Check the envelope, then ask for the batch on the Event Ingests board.
Bulk job `Failed`, every row `success`	The job failed as a whole and nothing was applied	Check the CSV header names the community's identifier field, then send a new batch.
No ingest row at all	The request never reached the platform	Confirm the exact URL the sender posted to resolves, and ask for the sender's exact request.

7. Cleanup

Undeploy when the pipeline should stop, then delete. A deleted workflow takes its run history with it, and ingest rows remain readable only through the sender's batch ids for a short window, so keep your own record of what a canary batch proved.

What the API does not cover

Sending a batch. The sender posts the envelope; there is no Workflow Builder route that submits one.

The bulk job's own status and per-row details, which are separate platform endpoints.

Reading ingest payloads in bulk. The Event Ingests board and its routes are a different surface, and the public status endpoint reads one batch summary.

Triggering a dispatch by hand.

Set up an event-ingest workflow and check batch status

The envelope contract#

1. Create the workflow with the ingest trigger#

2. Understand the two deduplication layers#

3. Route the rows to the right step, then validate#

4. Deploy, then read a batch's status#

5. Prove the batch end to end#

6. Failure handling#

7. Cleanup#

What the API does not cover#