Triggers and Scheduling

A trigger is what starts a workflow. Sovereign supports three ways to kick off a workflow execution: manually, on a schedule, or in response to an incoming webhook.

Manual Triggers

The simplest way to run a workflow is to trigger it yourself.

From the Studio: Click the Run button in the toolbar. The workflow executes immediately with the current configuration. This is ideal for testing and one-off runs.

From the API: Send a POST request to the workflow execution endpoint. This lets you trigger workflows from scripts, other applications, or CI/CD pipelines. See API Overview for authentication and endpoint details.

Manual triggers can include trigger data — input values passed to the workflow at execution time. Steps in the workflow can reference this data using template expressions like {{ trigger.fieldName }}.

Scheduled Triggers

Scheduled triggers run your workflow automatically at regular intervals using cron expressions.

Setting Up a Schedule

You can create schedules for any published workflow. Each schedule includes:

• Name — a descriptive label for this schedule
• Cron expression — defines when the workflow runs
• Timezone — which timezone the schedule operates in (defaults to UTC)
• Configuration — optional: a saved configuration to use as input when the schedule fires

Common Cron Patterns

How Scheduling Works

The scheduling service polls for due schedules at regular intervals. When a schedule is due, it triggers the associated workflow as if you had clicked Run manually. The execution is tracked normally and appears in the execution history.

If a scheduled run fails, the failure is recorded in the execution history. The next scheduled run proceeds independently — a failed execution does not block future runs.

Webhook Triggers

Webhook triggers let external systems start your workflows by sending an HTTP request to a unique URL.

How It Works

1. Create a webhook trigger for your workflow in the management interface
2. Sovereign generates a unique webhook URL for that trigger
3. Share the URL with the external system (e.g., a payment processor, a version control system, or a monitoring tool)
4. When the external system sends a request to that URL, the workflow executes with the request body available as trigger data

Security

Webhook endpoints support HMAC signature verification. When configured, every incoming request must include a valid signature proving it came from your authorized external system. Requests with invalid or missing signatures are rejected.

Response Modes

Webhook triggers support two response modes:

• Fire and forget — returns immediately with the execution ID. The caller does not wait for the workflow to complete. Use this for most integrations.
• Await completion — holds the HTTP response open until the workflow finishes (up to a configurable timeout). Returns the execution result directly. Use this when the caller needs the output immediately.

Trigger Data

The body of the webhook request is available to your workflow as trigger data. Steps can reference it using template expressions like {{ trigger.event }} or {{ trigger.payload.customer.name }}.

Saved Configurations

For workflows that accept input parameters, you can create saved configurations — pre-defined sets of input values that can be used by any trigger type.

Saved configurations are useful when:

• You want to run the same workflow with different inputs (e.g., different environments, different customers)
• A schedule should always use specific input values
• You want to expose "one-click" execution options in the UI

Next Steps

• Expressions and Data Flow — use trigger data in your workflow steps
• Monitoring Executions — track runs triggered by schedules and webhooks
• API Overview — trigger workflows programmatically