Understanding Workflow Trigger Types

Overview

Every workflow starts with a trigger — the condition that tells gaiia when to run it. The trigger type you choose determines not just how a workflow starts, but what it's suited for, who initiates it, and how it fits into your broader operations.

In this article, we'll be covering the four trigger types, when each one is the right choice, and how to think about the tradeoffs between them.

Select a trigger type

When you open a new workflow with no trigger configured, the canvas shows a Select a trigger button. Click it to open the trigger configuration panel in the right sidebar.

The sidebar lists all four trigger types — Event, Manual, Schedule, and Webhook. Select the one that fits your workflow to begin configuration.

Not sure which to pick? The sections below explain each trigger type in detail, including when to use it and how it behaves.

Understanding the four trigger types

Using the event trigger types

Event triggers fire automatically when something changes in gaiia — an account is created, a work order status is updated, a ticket is closed. You choose the event type when setting up the trigger, and the workflow runs every time that event occurs.

Because the trigger fires without any manual action, event-triggered workflows are the most hands-off option. Once enabled, they run silently in the background, responding to your data as it changes.

Use an event trigger when:

• The workflow should run every time a specific change occurs, without exceptions
• The action should happen immediately when the event fires, not on a delay
• No human judgment is needed to decide whether the workflow should run

If a workflow should only run for some events of a given type — for example, only when a work order reaches a specific status — you can add a skip execution mapper to the trigger to filter out runs that don't meet your criteria. See Skip Execution Mapper for details.

Using the manual trigger type

Manual triggers can be started in two ways: by a user clicking a button on a specific record in the gaiia UI, or by another workflow calling this one using the Start Workflow node. In both cases, the workflow receives a record ID as its input and proceeds from there.

This dual nature makes manual-triggered workflows useful both for human-in-the-loop actions and as reusable building blocks. A single manual workflow can handle a discrete piece of logic — sending a communication, provisioning a service, updating a record — and be called from any number of other workflows that need that behavior.

Use a manual trigger when:

• Someone on your team needs to decide whether and when to run the workflow
• The workflow acts on a specific record a user is already looking at
• The action is occasional or situational rather than automatic
• You want to encapsulate reusable logic — such as provisioning, communications, or record updates — that other workflows can call via the Start Workflow node

Using the schedule trigger type

Schedule triggers run a workflow automatically at a defined time or interval, expressed as a CRON expression. The workflow isn't tied to any specific record or incoming event — it runs on the clock, whether that's every night at midnight, every Monday morning, or on the first day of each month.

Scheduled workflows are well-suited to batch operations: pulling a report across all accounts, checking for records in a stale state, sending a regular digest, or any task that should happen on a predictable cadence regardless of what else is happening in the system.

Use a schedule trigger when:

• The workflow should run on a fixed cadence, not in response to a specific change
• The work involves processing a set of records rather than responding to one
• Timing matters more than immediacy — the task can wait for its scheduled window

CRON expressions follow standard five-field syntax (minute, hour, day of month, month, day of week). If you're not familiar with CRON, tools like crontab.guru can help you build and validate expressions.

Using the webhook trigger type

Webhook triggers give your workflow a unique URL that external systems can send data to via HTTP POST. When a POST request arrives at that URL, the workflow runs with the request payload as its input — no polling, no manual action required.

This makes webhook-triggered workflows the right choice for integrations where the other system is the source of truth for when something should happen: a payment processor confirming a transaction, a provisioning platform signaling that a device is ready, or any third-party service that supports outbound webhooks.

Use a webhook trigger when:

• An external system needs to initiate the workflow, not gaiia
• You want the workflow to run immediately when the external event occurs
• The incoming payload contains data the workflow needs to act on

Each webhook-triggered workflow has its own unique URL. You can optionally define an input schema to validate the incoming payload before the workflow runs, and a skip execution mapper to filter requests conditionally. See Skip Execution Mapper for details on filtering webhook requests.

Choosing the right trigger type

Most workflows fit naturally into one trigger type once you've answered a few questions:

• What starts the need for this workflow? If it's an event inside gaiia, use Event. If it's a person making a decision or another workflow calling this one as reusable logic, use Manual. If it's the clock, use Schedule. If it's something outside gaiia, use Webhook.
• Should every occurrence trigger a run, or only some? Event triggers fire on every matching event — use a skip execution mapper if you need to filter. Manual triggers only run when a user chooses to start them.
• Does the workflow need to act on a specific record right now, or across many records over time? Event and Manual triggers are record-focused. Schedule triggers are better suited to batch work across multiple records.

It's also worth noting that trigger types can work together. A common pattern is an event-triggered workflow that detects a change and then launches a manual-style or inventory-based workflow on a specific record. The trigger type shapes the entry point — the rest of the workflow logic is the same regardless of how it started.