Running Workflows

Workflows can be executed through four methods: API calls, webhook events, scheduled triggers, or directly from the visual builder. Each execution creates a run with a unique ID, full step-by-step logging, and output capture.

Execution Methods

From the Visual Builder

Click the Run button in the top-right corner of the canvas to execute the current workflow. You can provide test input data in the run dialog.

Via API

curl -X POST https://api.justpaid.io/api/v1/workflows/{WORKFLOW_ID}/run \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"customerId": "cus_123"}}'

const response = await fetch(
  `https://api.justpaid.io/api/v1/workflows/${workflowId}/run`,
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.JUSTPAID_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ input: { customerId: 'cus_123' } }),
  }
);
const { data } = await response.json();
console.log('Run ID:', data.runId);

Via Webhook

External systems trigger workflows by sending HTTP POST requests to your webhook endpoint. See Webhook Triggers for configuration details.

Via Schedule

Workflows with schedule triggers execute automatically at configured intervals. See Schedule Triggers for cron syntax and timezone configuration.

Run Lifecycle

Every workflow run progresses through these states:

pending -> running -> completed
                   -> failed
                   -> timed_out

Checking Run Status

curl https://api.justpaid.io/api/v1/runs/{RUN_ID} \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch(
  `https://api.justpaid.io/api/v1/runs/${runId}`,
  { headers: { 'x-api-key': process.env.JUSTPAID_API_KEY } }
);
const { data } = await response.json();
console.log('Status:', data.status);
console.log('Output:', data.output);

Error Handling

Each step supports three error handling modes:

Configure per step:

{
  "id": "send-invoice",
  "type": "action",
  "errorHandling": "retry",
  "retryConfig": {
    "maxAttempts": 3,
    "backoffMs": 1000
  }
}

Timeouts

Set a maximum execution time for the entire workflow or individual steps:

{
  "settings": {
    "timeoutMs": 300000
  }
}

Individual step timeouts override the workflow-level timeout.

Concurrency

Control how many instances of a workflow can run simultaneously:

{
  "settings": {
    "concurrencyLimit": 1
  }
}

Setting concurrencyLimit: 1 ensures runs execute sequentially, which is important for workflows that modify shared state.