Processexecutions overview
The Process Orchestration APIs are currently available as a Non-Production Preview (NPP) feature and are not available to all clients. For more information, see Process Orchestration.
When an External Orchestration process reaches a step that requires a response from an external system — for example, waiting for a payment gateway to confirm a transaction or for a third-party service to return a result — the process pauses and enters a wait state. The Process Executions API is the mechanism for resuming that paused process.
Your external system performs its work and then calls this API to deliver a callback message containing the result. The process engine receives the message, resumes the waiting process instance, and continues execution from where it paused.
Endpoint summary
| Method | Path | Description |
|---|---|---|
POST | /processexecutions/{executionId}/messages/{messageName}:deliver | Deliver a callback message to a paused process execution |
How it works
- A process instance starts (via the Process Instances API).
- The process reaches a wait state — an intermediate message catch event declared with
<mbu:callback message="...">— and pauses. - The process engine injects the execution ID and message name into the outbound request as
X-Callback-Execution-IdandX-Callback-Messageheaders, so your external system knows which execution and message to resume. - Your external system completes its work (for example, processes a payment or calls a downstream API).
- Your system calls
POST /processexecutions/{executionId}/messages/{messageName}:deliverwith the result payload. - The process resumes and continues with the data from the callback.
A 409 Conflict is returned if messageName does not match the message the execution is actually waiting on.
Callback message
The callback payload is a free-form JSON object whose shape depends on what the waiting process step expects. Consult the BPMN process definition to determine the required fields.
This API is used to resume processes waiting for external callbacks. To start a new process instance or query instance history, use the Process Instances API.