Triggers

Triggers are the entry nodes that start workflow Runs. Every workflow needs at least one — the editor's Test button stays disabled until you add an executable trigger node. A workflow can have several triggers, and each one starts runs independently.

Running and Paused

Production has two independent controls:

  • Publish freezes the exact Draft as an immutable Release and makes it Current. Production never falls back to a Draft or another mutable workflow copy.
  • Start lets the Current Release accept new production entries; Pause rejects new entries without changing Current. A workflow's first Publish remains Paused until you explicitly Start it.

While a workflow is Paused, schedules do not fire, webhook requests are rejected, and record events pass it by. You can still click Test in the editor to run the current Draft. Pausing does not interrupt runs already in progress: every admitted run continues with the immutable Release and execution settings it captured at admission.

Publishing or restoring a Release updates the workflow's production trigger registrations. If no Current Release exists, every production entry is rejected rather than falling back to authoring state. Archiving makes the workflow unavailable for new production entries while preserving its Draft, Releases, and run history; restoring the workflow returns it to its prior Running or Paused state.

Disabling an individual trigger node removes it from the executable graph. It stays visible for later editing and remains in Release history, but does not register or start production runs. Disabled action nodes and disabled edges are likewise skipped during execution.

Message and Call bindings also have their own per-binding availability control (see below). A binding can admit work only when it is available, its trigger node is executable in the Current Release, and the workflow is Running.

Manual start

Starts the workflow on demand. Click Test in the editor to run the current Draft as a debug run. For production, Publish a Release, Start the workflow, and use Run now from the Workflows list. Outputs include the input the run was started with (output), the trigger time, who started it, and a context object with timestamp, user, workspace, and workflow details.

The actor's triggered_by.tenant_id identifies the workspace where the run executes, including when you switch from your default workspace, and context.user.tenant_id identifies that same workspace. These fields describe the run; they do not grant permissions.

Workflow inputs

Under Workflow inputs in the node settings, declare the values a run starts with. Each input has a name, a type (string, number, integer, boolean, object, a list or a saved shape) and optionally a label, a description, a default, a list of allowed values, and Required. Every input becomes its own port on Manual start, so the next step can be wired to customer_id directly instead of reading it out of output. A name cannot be one Manual start already uses for a port (output, triggered_at, triggered_by, tenant, workflow, context, agent, run) or config.

Whoever starts the run sends the inputs as one object, such as {"customer_id": "acme", "dry_run": true}: the Test input in the editor, input_data for MCP workflow_run start, the input a Run workflow step passes to this workflow, or the input of an app's run tool. The input is checked before the run exists:

  • An input that is missing takes its default. A required input with no default must be sent.
  • Each value must match its type and, if set, one of its allowed values.
  • A key that no input declares is refused when the person or step starting the run chooses the keys: Run now, Test, MCP, Run workflow and app tools. Inputs built by Rollout itself keep their extra keys: a Repeat workflow step's state and iteration, a stream dispatch event, a retry or a re-run of an earlier run.

A refused start names every field that failed, such as 'customer_id' is required; 'region' is not a declared input, and no run is created. A Run workflow, Repeat workflow or app run step fails with those fields in its error. The run's input, as shown on the run, is the checked input with defaults filled in.

Run now in the Workflows list asks for the declared inputs before it starts the Current release, in a form with one field per input, prefilled with its default. In the editor, Test with inputs… shows the same form for a Manual start. See Start a run with inputs. A Manual start with no declared inputs starts on the click and accepts any object, as before.

Dragging a field from one of Manual start's ports onto another step's input, such as tenant.id, adds an extracted value instead. Extracted values appear collapsed under Extracted values; they are read from that port and are not inputs, so a Manual start whose entries are all extracted values still accepts any object.

Tasks assigned to an agent start the workflow with the task's own details rather than these inputs. A task route can only use a Manual start whose required inputs all have defaults; binding one with a required input that has no default is refused and names the input.

Schedule

Starts the workflow on a recurring cron schedule.

  • Cron Expression — standard 5-field cron: minute, hour, day of month, month, day of week. Examples: 0 9 * * * (daily at 9:00), 0 0 1 * * (1st of each month at midnight), */30 * * * * (every 30 minutes).
  • Timezone — IANA timezone the schedule is evaluated in. Defaults to UTC.
  • Description — optional human-readable note, echoed on the node's schedule output.

Schedules are checked once per minute, and a trigger never fires twice within the same minute. An invalid cron expression can remain in your autosaved Draft, but Publish rejects it so a broken schedule cannot become Current.

Workflow finished

Starts a workflow when any selected upstream workflow reaches a terminal state. Use it to model dependencies directly instead of coordinating several workflows with hand-picked cron minutes.

  • Workflows — one or more upstream workflows to observe.
  • Statuses — completed, failed, or cancelled; defaults to completed.
  • Outcomes — optional finer-grained filter: ok, with_warnings, with_errors, no_op, failed, or cancelled.
  • Debounce — suppresses another accepted invocation of this trigger for the configured number of milliseconds. Zero, the default, fires once per matching upstream run.
  • Loop limit — how many times this workflow may run in one chain of runs that start each other, counting the first. Defaults to 3; set 1 to 50. Raise it for a loop you build on purpose, such as a fix-and-review cycle.

The node emits the upstream run envelope and its final results, plus the normal tenant, workflow, and agent entry metadata. Deliveries are durable and deduplicate by upstream run id, so retrying the dispatch job cannot start the same entry twice.

Only terminal production runs emit completion events; editor tests do not cascade into production workflows. The downstream workflow's current runtime audience must still be allowed to read the upstream workflow before any result payload is exposed. Publish rejects direct self-references.

Longer cycles stop at the loop limit: when this workflow already appears that many times in the finished run's chain of derived runs, the finish does not start it. The finished run shows a notice naming this workflow, its trigger node, how many times it ran and the limit, so a stopped loop is visible on the run where it stopped. A limit you change applies after you Publish, and raising it does not restart finishes it already stopped.

Incoming webhook

Starts the workflow when an HTTP request hits the trigger's endpoint. Each webhook trigger gets its own URL containing an unguessable token:

POST https://<your-workspace-host>/webhook/<token>

Requests to /api/hooks/<token> reach the same endpoint. Publish a Release containing the executable trigger and Start the workflow before sending requests. Requests are rejected while the workflow is Paused or the trigger node is disabled; unknown tokens return 404.

A successful delivery responds with 202 and a JSON body containing the run id and a status of enqueued, or deduped when the delivery was recognized as a repeat.

Request data

The node echoes the request to downstream nodes: method, path, query parameters, and parsed body. Include Headers and Include Raw Body are both off by default; turn them on only when a downstream node needs them. Sensitive headers (authorization, cookies, API keys, signatures) are always redacted when headers are included.

Signature verification

Select or create a tenant secret in HMAC Secret to require a valid signature on every request. The workflow stores only the secret reference; plaintext HMAC values are rejected:

  • Signature Header — where the signature arrives. Defaults to X-Signature; prefixes like sha256= are accepted.
  • HMAC Algorithm — sha1, sha256 (default), or sha512, computed over the raw request body.
  • Timestamp Header — optional. Set it to enforce freshness: the header must carry an ISO 8601 timestamp within Timestamp Tolerance (default 300 seconds), and the signature must cover timestamp + "." + raw body. Leave blank for providers that don't send one.

Requests with a missing or wrong signature return 403. See Security for how stored secrets are protected.

Deduplication and event identity

Redelivered events don't start duplicate runs. Signed requests deduplicate from the exact authenticated preimage, so changing an unsigned delivery header cannot replay the same signed event. For unsigned requests, the delivery key comes from, in order: the configured Delivery Key Header, a known provider delivery-id header (GitHub, GitLab, Atlassian, and similar), or a hash of the request body.

Provider Slug and Event Type Header shape the node's event and event_type outputs (for example webhook.github.push), which is useful when one endpoint receives several event types.

Handshakes and limits

  • GET and HEAD requests to the webhook URL return 200, so providers that validate URLs before delivering events can complete their handshake.
  • Request bodies are limited to 256 KB (413 beyond that).
  • Deliveries are rate limited to 100 requests per minute per workspace (429 when exceeded).

Record created and Record updated

Start the workflow when a record changes. Pick the Object — Task, Project, or a Custom Object (see Objects & Records) — then narrow with optional filters:

  • Tasks: Filter by Project and Filter by Task Type.
  • Custom records: Custom Object selects which type fires the trigger.
  • Record updated only, for tasks: New status fires only when the updated task's status matches a status slug such as in-progress.
  • Record updated only: turn off Any update alongside New status to ignore unrelated edits. The trigger then fires only when task_status_id is among the changed fields and the new status matches the filter.

Use Condition for a brace-free expression that is checked before a run starts. The expression scope contains record, changed_fields, previous_data, and event_type. For example:

TEXT
record.data.importance >= 5 && contains(changed_fields, "importance")

For a Task custom field, leave Any update on and leave New status blank. For example, start a deployment workflow only when the phase changes to deploy:

TEXT
contains(changed_fields, "shared_fields.delivery__phase") && record.shared_fields.delivery__phase == "deploy"

Task updates carry current values in record.shared_fields and prior values in record.previous_shared_fields. You can also check where the phase came from:

TEXT
record.previous_shared_fields.delivery__phase == "build" && record.shared_fields.delivery__phase == "deploy"

Use the composed field key (<group>__<field>). A shared-field-only write that repeats the same normalized value emits no update event, so a workflow's own repeated write does not start another run. Updates to other fields still emit events; the contains check excludes them.

Both maps include only known, enabled fields bound to the Task's destination Project or workspace scope. Sensitive fields are omitted entirely, including their changed-field names. On a Project move, a prior stored value must also have a known, non-sensitive source definition; otherwise that key is omitted from both maps. A binding change alone does not count as a value change.

An empty condition always passes. Invalid expressions are rejected when the workflow is saved; a legacy condition that fails during evaluation skips the event instead of starting an unguarded run. Conditions are evaluated only after the workflow's persisted runtime audience is authorized to read the current source record.

Record created emits the full created record. Record updated emits the full updated record, its id, title, project, current and previous status, previous_data, and changed_fields. Both triggers also expose the standard entry metadata outputs: run, tenant, workflow, and agent.

Skipped matching triggers emit rollout.workflows.entity_trigger.skipped.count, tagged by reason (filter_mismatch, condition_false, condition_invalid, or source_unavailable) so operators can distinguish a quiet condition from an authorization or configuration problem.

Run from a record

Runs the workflow on demand from a record's page rather than automatically. Configure the Object — Task, Project, Team, Objective, or Custom Record — plus optional project, task type, or team filters that control where the workflow is offered.

Matching workflows appear in the Workflows panel of the record's sidebar with a Run button. Clicking Run starts the Current Release with that record and the person who clicked as inputs. Only Running workflows whose Current Release contains an executable matching trigger are offered.

Message and Call

Entry nodes for conversational agents. Instead of node settings, both are configured through bindings: a binding connects an agent identity to a source — a chat channel, a DM, or a bot Connection — and authorizes it to act there. Open the node's settings sidebar and click Add binding, then pick the Agent and Source. Each binding has its own availability control. Manage agent identities under Automation → Agents.

  • Message — starts a run when the bound agent is mentioned in the source. The optional Mention token overrides the trigger word; it defaults to the agent's handle. The node emits the message text, the full message, the author, attachments, and a dispatch envelope to wire into a Reply node.
  • Call — starts a run when a call begins in the bound channel or DM. The node streams the participant's live audio into the flow (wire it into Speech to Text) and emits the call's metadata.

New email, row or file

A polling trigger: checks a Gmail inbox on an interval (Poll Interval, default every 60 seconds) and starts the workflow for messages matching your filters. Requires a Google Connection.