Running Workflows¶

Once you’ve created a workflow, you can run it manually, on a schedule, or from external events via webhooks. This guide covers execution methods, safety modes, and where to monitor results.

Overview¶

Workflows run asynchronously in the background. When triggered, steps run in order, and outputs from earlier steps can be used by later steps. You can monitor progress and review execution history after completion.

Key characteristics: - Clear step-by-step visibility: You can inspect what happened at each step (inputs, outputs, and any errors) - Variable passing: Steps can reference values produced earlier using {{ ... }} placeholders - Safety-first for writes: Destructive or high-impact actions can require stronger confirmation before executing - Cost awareness: The product can check limits and show cost previews before live runs

See Virtual Run Preview for the recommended “preview before execute” flow.

Trigger Types¶

Manual Execution¶

The simplest way to run a workflow is clicking the Run button in the workflow editor or workflows list.

When to use: - Testing a workflow before scheduling it - Running one-off tasks - Debugging step-by-step behavior

How it works: 1. Click Run on your workflow 2. Optionally provide input parameters if prompted 3. Watch the execution progress in real-time 4. Review results when complete

Scheduled Execution (Cron)¶

Schedule workflows to run automatically at specific times. The system supports flexible scheduling options.

When to use: - Daily reports (e.g., "Send me a summary every morning at 9 AM") - Recurring tasks (e.g., "Check for new leads every hour") - Maintenance jobs (e.g., "Clean up old data every Sunday")

Setting up a schedule:

When creating or editing a workflow, choose "Scheduled" as the trigger type and configure:

Common schedule examples:

Notes: - Scheduled workflows may check account limits before running. If limits are exceeded, the run may be skipped. - Times are evaluated in your specified timezone, so “9 AM” means 9 AM in your local time.

Webhook Triggers¶

Trigger workflows from external services by sending an HTTP POST request to a unique webhook URL.

When to use: - Respond to events from other systems (e.g., "When I receive an email...") - Integrate with services that support webhooks - Build event-driven automations

Setting up a webhook:

1. Create or edit a workflow and choose "Webhook" as the trigger type
2. Save the workflow to generate your webhook URL and secret
3. Copy the webhook URL (looks like https://your-domain.com/webhook/{workflow-id})
4. Configure the external service to POST to this URL

Webhook request format:

POST /webhook/{workflow-id}
Content-Type: application/json
X-Webhook-Signature: {hmac-sha256-hex}

{
  "your": "payload",
  "data": "here"
}

Security: - Each webhook has a unique secret for signature verification - Include an HMAC-SHA256 signature of the raw request body in one of these headers: - X-Webhook-Signature: <hex> - X-Hub-Signature-256: sha256=<hex> (GitHub-style format) - The signature is computed as: HMAC-SHA256(secret, raw_request_body) and encoded as a hex string

Response:

On success, the webhook returns JSON including a run_id for tracking.

Using webhook data in your workflow:

The webhook payload and headers are provided to the workflow as trigger input. The editor will show which variables are available to reference in prompts and step configuration.

Execution Flow¶

When a workflow runs, here's what happens step by step:

1. Trigger received (manual click, cron schedule, or webhook)
         ↓
2. Workflow loaded from database
         ↓
3. Limit checks (where applicable)
         ↓
4. Run record created with "running" status
         ↓
5. For each step:
   ├── Resolve variables from previous steps
   ├── Execute the step action
   ├── Record step result
   └── Pass output to next step
         ↓
6. Run marked "completed" (or "failed" if error)

Monitoring Runs¶

Workflow Dashboard¶

Use the Workflows dashboard to:

• Search and filter workflows
• Organize with projects and tags
• Enable/disable workflows
• Apply bulk actions when managing many workflows
• Trigger runs and previews
• See recent run activity and status

Action Log¶

Use Action Log when you need details:

• Run-by-run history with step-level information
• Inputs and outputs (where available)
• Error messages and failure context for troubleshooting

Viewing Run History and Logs¶

Run History¶

Access your workflow's execution history from the Workflows page:

1. Navigate to Workflows
2. Find your workflow and click History (or expand the workflow card)
3. View a list of recent runs with:
4. Status: completed, failed, running, or skipped
5. Started at: When the run began
6. Completed at: When the run finished
7. Triggered by: manual, cron, or webhook
8. Duration: How long the run took

Step-by-Step Logs¶

Click on any run to see detailed step execution:

• Step name: What the step does
• Status: completed or failed
• Input parameters: What was sent to the step (with variable substitution shown)
• Output result: What the step returned
• Error message: If the step failed, why

This helps you: - Understand exactly what happened during execution - Debug failed workflows - Verify that variables resolved correctly

Handling Failures and Retrying¶

Automatic Retries¶

Some transient failures may be retried automatically (for example: temporary network issues or rate limiting). This helps workflows recover from short-lived problems without manual intervention.

Common transient issues include: - Temporary network errors - Rate limiting from external services - Brief service outages

Manual Retry¶

If a workflow fails after all retries, you can manually retry:

1. Open the failed run from the History view
2. Review the error to understand what went wrong
3. Fix any issues (e.g., reconnect a service, update parameters)
4. Click Retry to run the workflow again

Common Failure Reasons¶

Viewing Error Details¶

When a run fails, the error message appears in: - The run history list (summary) - The step execution details (full error)

Look at the step that failed and its input parameters to diagnose the issue.

Enabling and Disabling Workflows¶

Disabling a Workflow¶

To temporarily stop a workflow from running:

1. Go to Workflows
2. Find the workflow
3. Click the Enabled toggle to turn it off

When disabled: - Scheduled runs are skipped - Webhook triggers are ignored - Manual runs still work (for testing)

Re-enabling a Workflow¶

Toggle the Enabled switch back on. The workflow will: - Resume running on its schedule (if cron-triggered) - Accept webhook triggers again - Continue normal operation

Why Disable?¶

Common reasons to disable a workflow: - Maintenance: While updating the workflow configuration - Debugging: To investigate issues without triggering more runs - Cost control: To pause automated runs while you're away - Seasonal: For workflows that only run at certain times of year

Best Practices¶

Testing Before Scheduling¶

1. Virtual Run first: Use the Preview feature to see what will happen
2. Manual Run second: Execute once manually to verify real behavior
3. Schedule last: Only enable the schedule after confirming it works

Monitoring Active Workflows¶

• Check the History regularly for failed runs
• Set up notifications for critical workflows (if available)
• Review step outputs periodically to ensure expected behavior

Managing Credits¶

• Automated triggers may check account limits before running
• If a run is skipped or blocked for billing/limits, review Billing and adjust settings as needed