*Workflows › Build*

# Triggers

> A trigger decides when a workflow runs. Every workflow has exactly one, and you can change it in the editor at any time (until you publish, nothing changes for the runs).

## The seven triggers

| Trigger | Starts a run when | Needs the workflow live? |
| --- | --- | --- |
| «Manual run» (`manual`) | An administrator presses the button, or the REST API or MCP asks for it. It can declare a form. | No |
| «Manual run (from a record)» (`entity`) | An administrator chooses "Run workflow" on a record. One kind of record per workflow. | No for the server and the API; the record page and the dashboard show a paused or never-published workflow greyed out, with the reason |
| «From another workflow» (`workflow`) | A step of another workflow starts it. It has no button. | No |
| «Scheduled» (`schedule`) | The clock reaches the next time of a cron expression. | Yes |
| «Webhook» (`webhook`) | Your system posts JSON to the workflow's address. | Yes |
| «Event» (`event`) | Something happens in Filmo (an order is reserved, an invoice is validated…) or in a connected account (an email arrives). | Yes |
| «Signal» (`signal`) | Another workflow fires a named signal this one listens for. | Yes |

The names in the first column are the ones in the palette. Two different triggers are both labelled "Manual run" there: the one under Utilities is the manual trigger with its form; the one inside each record's drop-down in the Filmo group is the "from a record" trigger.

## When a trigger takes effect

- A trigger starts doing something only after you «Publish». The editor rebuilds the lookup that decides what fires when a version is published, never when a draft is autosaved.
- The automatic ones (schedule, webhook, event, signal) also need the «Live» switch on. A workflow that is paused, archived or never published fires nothing.
- The manual, from-a-record and from-another-workflow triggers do not depend on Live in the engine: a paused workflow can still be run from the editor, through the API or called from another workflow. The record page and the dashboard list those workflows too, but a paused or never-published one appears greyed out with the reason and cannot be run from there.

**Edit, publish and go live**
- You (editor) → Draft: Edit the canvas: autosave Saved after a short pause. It writes only the draft and marks it as «Unpublished changes». What runs does not change.
- You (editor) → Published version: «Publish» Freezes the draft as a new numbered version and rebuilds the triggers. New runs use it; runs already in flight keep theirs.
- «Live» on: automatic triggers (schedule, webhook, event, signal) fire and start runs of the published version
- You (editor) → Draft: «Discard» The draft goes back to the published version. There is no way back to an older one.
- You (editor) → Published version: «Run workflow» A manual run uses the published version. If the draft has unpublished changes, the editor publishes them first.

## Manual

Use it for work someone starts on purpose, or for a workflow your own system starts through the [REST API or MCP](https://docs.filmo.io/workflows/api-and-mcp). Declare the form in the trigger: each field has a name, a label and a type (the editor offers boolean, number, text and date).

- Field names start with a letter or underscore and use only letters, digits and underscores. `createdAt` and `createdBy` are reserved, because the trigger publishes them itself, and a name cannot repeat.
- Every declared field must be sent when someone runs the workflow (the API rejects a missing one with 422). There are no optional fields and no default values, although the form does not stop you leaving a text field empty. A workflow with no fields runs straight away, with no dialog.
- Only administrators can run a workflow. Pressing the button from the editor publishes first if the draft has changes.
- The trigger publishes `trigger_createdAt` (when the run was queued) and `trigger_createdBy`, plus one variable per field. `trigger_createdBy` is the creator of the workflow, [not the person who pressed the button](https://docs.filmo.io/workflows/permissions#run-actor).

## From a record

A workflow with this trigger appears under «Run workflow» in the action menu of the record page (and in the quick-actions search), for administrators. It has no form: it receives the record itself. A workflow is tied to one kind of record (the list is on the [trigger's reference page](https://docs.filmo.io/workflows/reference/triggers/entity#records)), and the kind cannot be changed after you choose it, because the expressions refer to it.

- The record is checked before the run is queued and loaded again when the run starts. If it was deleted in between, the run fails with "the record the workflow was launched on no longer exists".
- The trigger publishes the same fields as the event triggers of that record (see below), under `trigger_<record>`.
- Through the REST API it needs the id of the record in `payload.entityId`; without it the request is rejected.

## From another workflow

It has the same form as the manual trigger, but no button and no API: only a «Trigger workflow» step of another workflow can start it. That makes a call with a contract: the caller picks the target and fills in its form. Pressing the button, or calling the API, answers 409. The caller does not wait for the result; see [Signals and chaining workflows](https://docs.filmo.io/workflows/signals-and-chaining).

## Schedule

Use it for work that happens on the clock. You give a cron expression and a time zone. A standard five-field expression works, and so does one with six fields (seconds), but the engine looks at the clock once a minute, so the shortest interval is one minute. The editor offers presets («Every minute», «Every hour», «Weekdays at 08:00» and so on) and a «Custom» field that describes your expression in words.

> **Time zone:** The time zone defaults to the zone of the browser of whoever picks the trigger, not to the company's time zone. A colleague in another country can bake their zone in without noticing. Check the «Time zone» field of every scheduled trigger.

- The publish computes the next time from "now". If you publish again without changing the expression or the zone, the next time is kept.
- A run starts up to about a minute after its time. `trigger_scheduledAt` holds the planned time; `trigger_createdAt` holds when the run was really queued.
- At most one run per occurrence. If the platform was down, you get one run for the occurrence that is overdue and then the clock jumps to the next future time: missed occurrences are not made up.
- While a workflow is paused, occurrences pass silently. Switching «Live» back on does not run what you missed.
- The templates that run on a schedule use Europe/Madrid, written into the trigger.

## Webhook

Use it when your own system should start a workflow. It is a POST to a private address with a secret. The page [Incoming webhooks](https://docs.filmo.io/workflows/incoming-webhooks) has the full contract, including the part that surprises people: the body is validated against the type you declare after Filmo has already answered 202.

## Event

Use it to react to something that happened in Filmo or in a connected account. Pick the event from the palette (the Filmo group has one drop-down per kind of record; connected accounts have their own sections). The catalog is closed: only the events in it exist. For the full list and the fields each one carries, see the [event reference](https://docs.filmo.io/workflows/reference/events).

### What an event carries

Each event publishes two variables:

- `trigger_event`, the envelope: the event name, the kind and id of the record, its name, the action code, who made the change (`actor.kind` is user, contact or system, with an id and a name) and where it came from (`origin`).
- `trigger_<record>`, a projection of the record with only the fields the event lists (an order has its number, status, contact, dates and so on, but not its lines or its total). To read more, add a step that fetches the record.

`origin` tells you how the change was made: Neo, Automation (made by a workflow), API, MCP or Integration. A change made in the app itself carries no origin, so a filter "origin is App" can never match.

### Only when…

An event trigger can carry one condition, «Only when», or, for the update events that report what changed, «Only when this changes» (some update events can). The condition is evaluated when the event is received, against the published version, before any run exists.

- It is one comparison, with no and/or. The value on the right is always a literal.
- It fails closed: it must evaluate to exactly true. A missing variable or a null means no run, silently (except with "is not equal to": a missing variable is not equal to anything, so that comparison is true and lets the event through). A type mismatch also means no run.
- An event that does not pass leaves no run at all, not even a failed one. If a workflow never fires, check the filter first; see the troubleshooting page.
- Comparing a date with an instant (`2026-09-04` against `2026-09-04T00:00:00.000Z`) is never equal, and "is after" or "is before" compare them as text, which can match wrongly. Compare like with like.
- «Only when this changes» looks at what the emitting action reports as changed; a partial save that touches other fields reports nothing, and so does not pass.
- A change in the filter takes effect when you publish it, not when you edit it.

### Which changes are events

- Only the catalog events exist. Several things that look like events are not: moving a serialized unit through prepare, deliver or return, bulk stock changes, email delivered or opened, tags, availability and most imports do not trigger a workflow.
- Some records have a delete event (contacts, tasks, incidents, items, quotes, invoices and others, but not orders, projects or vehicles). It carries only the snapshot of what was deleted, not the live record.
- Writes made through the REST API and MCP go through the same path as the same change in the app, so they fire the same events, with `origin` set to API or MCP. That holds when the action behind the endpoint is one of the catalog events; whether every endpoint's action is one is not documented endpoint by endpoint. See what a write through the API sets off in the overview.
- An event of a change in Filmo is sent after the response is returned and is not retried if the send fails. Events of connected accounts that fail are replayed.

> **Loops:** A workflow that writes to a record can fire events of its own. Filmo cuts a chain of workflows at ten hops and never runs a workflow that is already in the chain, so a workflow does not fire on its own effect. A system that calls the API with a key has no run id, so the guard does not cover it: keep that call away from the data that starts the workflow.

**From a change in Filmo to a run**
- Change → Filmo: A record is created, updated or deleted From the app, the REST API, MCP, the AI assistant, the customer portal, an integration or another workflow.
- Recorded in the activity log, then turned into a catalog event. Only the events of the catalog exist as triggers; the event is sent after the response and is not retried if it fails.
- Filmo → Workflows: Match: Live workflows with that event A workflow that is already in the chain that caused the event is skipped, and a chain of more than ten hops is cut.
- Each workflow applies its «Only when» / «Only when this changes» filter. An event that fails it leaves no run at all, not even a failed one.
- Workflows → Filmo: One queued run per workflow that passes The same change never queues the same workflow twice.

### Events of connected accounts

| Source | What it needs |
| --- | --- |
| Email and calendar | A connected mailbox (Gmail, Outlook or iCloud), the email and calendar add-on, and a workflow created by the mailbox's owner: it fires only for workflows its owner created. |
| Xero | A connected Xero. Only for documents and payments linked to a Filmo record. Xero has no payment webhook: Filmo derives "paid" from the invoice changes, once per new payment. |
| Holded | A connected Holded. Holded sends nothing when a document is voided, so there is no voided event. |
| QuickBooks | A connected QuickBooks. |

The events of each source are listed in the event reference, in the sections linked in the first column.

A trigger for an account that is not connected can be published and set live and will simply never fire; Filmo does not stop you.

### Who the run acts as

The run acts as the workflow's creator, never as the person who made the change, even when the change was made by a customer in the portal. See [Permissions](https://docs.filmo.io/workflows/permissions#run-actor).

## Signal

A signal trigger listens for a named signal that another workflow fires with data. Signals are defined by administrators in «Workflow signals» and are described in [Signals and chaining workflows](https://docs.filmo.io/workflows/signals-and-chaining).

## Variables each trigger publishes

Every trigger publishes its own variables (`trigger_…`) and every run also has `system_today`. The reference page of each trigger lists them: [manual](https://docs.filmo.io/workflows/reference/triggers/manual), [from a record](https://docs.filmo.io/workflows/reference/triggers/entity), [from another workflow](https://docs.filmo.io/workflows/reference/triggers/workflow), [schedule](https://docs.filmo.io/workflows/reference/triggers/schedule), [webhook](https://docs.filmo.io/workflows/reference/triggers/webhook), [event](https://docs.filmo.io/workflows/reference/triggers/event) and [signal](https://docs.filmo.io/workflows/reference/triggers/signal). `trigger_createdBy` is always the creator of the workflow.

`system_today` is the date the run was queued in the company's time zone. See [Waits and dates](https://docs.filmo.io/workflows/waits-and-dates#today).

> **Tip:** Prefer an event trigger with a filter over a schedule that polls every record: it runs only when something changed, and costs no credits on the days when nothing did.

---

Canonical URL: https://docs.filmo.io/workflows/triggers  
Last updated: 2026-10-09