On Action Required | INFONITE

Fired when the source asks for something only your customer can provide.

A one-time code sent to their phone, a push notification to confirm, a security question, an extra field the engine could not know in advance. The execution is paused, not broken, and it is waiting for you.

This is the one event you cannot replace with patience. The others tell you about a run that is progressing on its own; this one is a run that will expire unless you answer, and the window is the institution’s, not ours. The alternative is polling the state every few seconds for every execution in flight.

Read the state

Execution State answers 423 and carries form_schema — the exact fields to collect, with x-meta.timeout saying how long you have — and action_required_expires, the deadline as a date.

Collect the values from your customer

Ask for exactly what the form declares, nothing more. The values travel like any other secret: you may send them encrypted.

Send them back

Resume an Execution hands the answer over and the engine carries on from where it stopped.

MFA_REQUIRED

A strong-authentication challenge: a code, a push confirmation, a signature.

INPUT_REQUIRED

Anything else the engine needs and could not know in advance — a security question, a contract to choose.

producer says who is asking: engine while the login is being resolved, or the feature’s own code — accounts_read, say — when one feature raised the challenge on its own.

Move fast. A code issued by a bank expires on the institution’s timetable, usually a couple of minutes. Past the deadline the execution is aborted with ACTION_TIMEOUT and has to be started again.

This event only happens when you asked for it to be possible. An execution started with customer_interaction_available: false never pauses: if the source raises a challenge, the execution ends instead.

Fired when the source asks for something only your customer can provide. A one-time code sent to their phone, a push notification to confirm, a security question, an extra field the engine could not know in advance. The execution is **paused, not broken**, and it is waiting for you. **This is the one event you cannot replace with patience.** The others tell you about a run that is progressing on its own; this one is a run that will expire unless you answer, and the window is the institution's, not ours. The alternative is polling the state every few seconds for every execution in flight. <Steps> <Step title="Read the state"> [Execution State](api:GET/executions/handler/v1/{execution_id}) answers `423` and carries `form_schema` — the exact fields to collect, with `x-meta.timeout` saying how long you have — and `action_required_expires`, the deadline as a date. </Step> <Step title="Collect the values from your customer"> Ask for exactly what the form declares, nothing more. The values travel like any other secret: you may send them encrypted. </Step> <Step title="Send them back"> [Resume an Execution](api:PUT/executions/handler/v1/{execution_id}) hands the answer over and the engine carries on from where it stopped. </Step> </Steps> <CardGroup cols={2}> <Card title="MFA_REQUIRED" icon="fa-solid fa-shield-halved"> A strong-authentication challenge: a code, a push confirmation, a signature. </Card> <Card title="INPUT_REQUIRED" icon="fa-solid fa-keyboard"> Anything else the engine needs and could not know in advance — a security question, a contract to choose. </Card> </CardGroup> **`producer` says who is asking**: `engine` while the login is being resolved, or the feature's own code — `accounts_read`, say — when one feature raised the challenge on its own. <Warning> **Move fast.** A code issued by a bank expires on the institution's timetable, usually a couple of minutes. Past the deadline the execution is aborted with `ACTION_TIMEOUT` and has to be started again. </Warning> <Note> **This event only happens when you asked for it to be possible.** An execution started with `customer_interaction_available: false` never pauses: if the source raises a challenge, the execution ends instead. </Note>

Payload

The payload of this webhook request is an object.

app_idstringRequiredformat: "object-id"

The application this execution was launched with — the one your secret belongs to. Worth keeping when your product uses more than one, a sandbox and a production app being the usual case: every record and every event we send carries it.

customer_idstringRequired

The customer_id you supplied when the execution was initialised, returned as you sent it — so an answer can be routed to the right case with no lookup on your side.

execution_idstringRequiredformat: "object-id"

The execution this belongs to — the value you poll for the state and address every results endpoint with. Always present here: an event exists because an execution does.

event"action_required"Required

The event type: action_required.

datestringRequiredformat: "datetime"

When the event was raised, in UTC. Deliveries can arrive out of order — a retry is delivered after whatever came next — so order your own records by this, not by arrival.

customer_availablebooleanRequired

Whether the execution was started as one a person can answer (customer_interaction_available). When false, a challenge from the source cannot be solved and the execution ends instead of waiting.

status_reasonenumRequired

The precise reason for the state at the moment of the event — one of the execution reasons, or a feature’s own when producer names a feature. Branch on this and not on the message: it is a stable code. Every reason by family.

session_idstring or nullOptionalformat: "object-id"

external_execution_idstring or nullOptional

locking_hashstring or nullOptional

event_class"ExecutionEvent"OptionalDefaults to ExecutionEvent

Payload class discriminator — always this value for an execution event. If the same endpoint also receives flow events, branch on it first.

producer"engine" or enumOptionalDefaults to engine

Who raised it: engine for the execution itself — the login, typically — or the feature’s own code when a single feature is what needs something. An action_required from the accounts reader says accounts_read, so you know what is being asked for before reading the form.

status_messagestring or nullOptional

datamap from strings to any or nullOptional

Response

200

Successful Response

422

Validation Error