Triggers

Triggers start flows from outside events. A trigger is two things composed: an event source (what listens) and a mapping into one flow (what runs). Understanding the lifecycle — capture, adopt, enable, publish — is what makes triggers predictable.

What can be a trigger

Three natives ship with the platform, and the integration catalog adds thousands of app events:

Kind	Starts from
Webhook	An HTTP request to a generated URL.
Scheduled	Daily / weekly / monthly / interval schedules with a timezone (raw cron via CLI/API).
Email	A message to a generated address. Payload fields: from, subject, bodyText, bodyHtml, date, messageId.
App events	Catalog event sources — new CRM lead, new sheet row, new channel message, … Most require a connected account.

cai trigger search "airtable"     # discover event sources, incl. whether they need a connection
cai trigger props <nodeSlug> --event <eventKey>

Never conclude “there is no trigger for X” from this page — search the catalog.

Triggers are not the only production entry point: the authenticated API and agent workflow tools also start runs (versions and rails).

The lifecycle

1. Create. Creating a trigger deploys its source immediately — a webhook URL or email address exists, and app-event sources start listening. Capture begins before publish: publish gates execution, not capture.

2. Capture a sample. A trigger’s output type comes from a real captured event — there is no “declare the payload shape” step:

cai trigger test-events <triggerId> --allow    # arm capture for dev
# ...send a representative event (real request, real email, real app action)...
cai trigger events <triggerId>                 # list captured events
cai trigger select-event <triggerId> <eventId> # adopt one as the sample = the trigger's output schema
cai trigger test-events <triggerId> --disallow # DISARM — this is how setup ends

Downstream expressions are authored against the adopted sample’s type.

3. Enable, then publish. The enabled flag lives inside the workflow definition. Enable the trigger, then publish — live dispatch reads the flags frozen into the published state, so toggling after publish changes nothing live until the next publish.

4. Verify against dev with replay. The routine development check is replaying a captured event at the development version:

cai trigger replay <triggerId> <eventId> --target dev

A real incoming event executes the live version (once published) — it does not reach dev unless test events are armed.

The two hazards

Dual dispatch

If you publish while a trigger is enabled and still has test events armed, one real event runs both rails — dev and live, both real, both metered. A schedule in this state fires twice, forever. Publish detects it and requires explicit acknowledgment; the fix is disarming before publishing. cai trigger audit surfaces this (dual_dispatch_armed) and the rest of the lifecycle state.

Shadowing

When the same source is referenced by more than one trigger canvas, only the first enabled one starts a run per event; the rest are shadowed (shadowed_by_earlier_canvas in the audit). Multiple triggers are for multiple entry points, not for fanning one event out — fan out inside the flow instead.

Design notes

• One trigger routes into one flow, through the trigger canvas’s Run flow node — its mapping props come from the target flow’s declared inputs. A workflow can carry several triggers pointed at different flows.
• Scheduled triggers carry no payload. The flow must fetch whatever data it needs.
• Timezones are the user’s to choose. “At 9am” without a timezone is a question, not an assumption.
• The trigger view is its own canvas in the builder, separate from the flow canvas.

Example prompts

Add a trigger for new rows in my sheet, capture one real event, wire the flow from the sample, replay it against dev, then enable and publish. Confirm test events are disarmed before publishing.

Run cai trigger audit on this workflow and explain each issue it reports before we go live.