> ## Documentation Index
> Fetch the complete documentation index at: https://motiadev-docs-deployment-guide.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Triggers

> How Functions get invoked in an iii system.

## What a Trigger is

A Trigger is a binding that tells iii when to invoke a Function. The Trigger declares a type (the
kind of event that causes it to fire), a configuration (the per-type details, like an HTTP path or a
cron expression), and the function ID it invokes. When the corresponding event happens, the Trigger
fires and the Engine routes the invocation to a Worker that provides the Function. HTTP requests,
cron schedules, queue messages, state changes, log events, and stream events all become Function
invocations through Triggers.

## Trigger types

<Note>
  `worker.trigger()` and the `iii trigger` CLI command can invoke any registered Function via its
  `function_id` (see [Functions / Direct
  invocation](./functions#direct-invocation)). The trigger types described below
  are how Functions get bound to other event sources (HTTP requests, cron schedules, queue messages,
  etc.). Workers can define their own trigger types.
</Note>

Trigger types come from connected Workers. A Worker that can source events declares one or more
trigger types alongside their configuration schemas. The iii-http Worker provides the `http` trigger
type. The iii-cron Worker provides the `cron` trigger type. The iii-state Worker provides the
`state` trigger type. A Trigger of a given type can only be registered while a Worker advertising
that type is connected, because that Worker is what produces the events that fire it.

## Trigger components

A Trigger has three parts: a `type` (the kind of event, like `http` or `cron`), a `config` (the
per-type details, like an HTTP path or a cron expression), and a `function_id` (the Function to
invoke). Together they tell iii what event to listen for, how to listen, and what to call when the
event happens.

### Conditional triggers

A Trigger can also specify an optional `condition_function_id`, which can be any gating function
that returns truthy/falsey result. If specified the Engine invokes the condition function first and
the `function_id`'s handler will only execute if the condition function returns a truthy value.

Since Triggers are concerned with "when to do" and Functions are concerned with "what to do" these
conditional functions preserve that separation: the Function stays focused on its work instead of
accumulating per-Trigger guards that the developer has to link specific invocation paths. Using
condition functions correctly helps maintain Worker and Function composability.

## Trigger pipeline

When a Trigger fires, the Engine looks up its `function_id` in the live registry, finds a Worker
that currently provides the Function, and dispatches the invocation. The function handler sees the
payload alone, never the source of the Trigger or the type of event that fired it.

## Trigger Actions

Functions invocation can be controlled via Trigger Actions. The default, synchronous mode blocks
until the Function returns its result or the configured timeout fires. The fire-and-forget mode
(`TriggerAction.Void`) returns immediately, scheduling the Function to run without waiting for a
result. Synchronous invocations are appropriate when the caller needs the value the Function
returns. Fire-and-forget is for side-effect work where the caller does not need to wait.

<Note>
  Workers can also define their own `TriggerAction`s. The iii-queue Worker provides
  `TriggerAction.Enqueue({queue})`, which routes the invocation through a named queue with retries.
  See iii-queue for the queue mechanics.
</Note>

## Trigger lifecycle

Triggers move through four states. `registered` means the Trigger has been declared with the Engine.
`active` means the Trigger is currently listening for its event. `invoked` means an event has fired
the Trigger. `unregistered` means the Trigger has been removed. When the Worker that owns a Trigger
disconnects, all of its Triggers are unregistered automatically along with its Functions.

## Trigger conditions

A Trigger can carry an optional `condition_function_id` that runs before the handler. When the
Trigger fires, the Engine invokes the condition function with the same payload the handler would
receive. If the condition returns a truthy value, the handler runs; if not, the invocation is
skipped. Use this when the same event source should sometimes fire the Function and sometimes not,
without splitting the Trigger into separate event-source registrations.