API integration

The module exposes authenticated Magento REST services for definition management, runtime inspection, external triggers and task decisions. Use an integration token whose role contains only the required workflow resources.

Definition management

The management routes are under /V1/workflow. Definition codes identify individual resources.

Validate and simulate before publishing an API-supplied graph just as you would in Admin. Simulation requires the Simulate Workflows resource; publish, archive and restore require Publish Workflows; the remaining management calls require Manage Workflows (see ACL and security).

Start a workflow

POST /V1/workflow/triggers/api/{code} accepts a payload object for a definition with a compatible API trigger. The provider route also accepts the event name, event data and provider. A successful trigger response confirms that work was accepted; the run is still asynchronous.

Example request body:

{
  "payload": {
    "source": "procurement_portal",
    "request_id": "REQ-1048",
    "amount": 789.00
  }
}

The provider route uses this shape:

{
  "eventName": "purchase_request_submitted",
  "eventData": {
    "request_id": "REQ-1048",
    "amount": 789.00
  },
  "provider": "procurement_portal"
}

Use the API trigger when the caller already knows the workflow code and payload contract. Use the provider route when the event identity and provider should be included in the normalized workflow payload.

Add a workflow signature

Magento API authentication remains required. When Require Webhook Signature is enabled on the trigger node, the caller must also calculate the workflow headers described in Triggers and event payloads. Use a fresh nonce for every attempt. If a network timeout leaves the result uncertain, inspect the run by its external reference before sending the business event again with a new nonce.

Inspect runs and decide tasks

GET /V1/workflow/runs supports limit and offset values. GET /V1/workflow/runs/{runId} returns one run. Task decisions use POST /V1/workflow/tasks/{taskId}/decision with a decisionData object containing an allowed decision and any supported comment data.

Do not retry a task decision blindly after a timeout. Check the task in Magento Admin first because the original request may already have closed it.

Integration safeguards

Keep API-trigger permission separate from workflow publication and task operation. Validate payload size and field count at the sending system as well as in Magento. Use idempotent external reference values where the calling process may retry, and record the returned run identifier for support tracing.