---
description:
  A Trigger initiates a Flow on some internal or external event, such as an in-app activity, incoming webhook, cron job,
  execution of Operation(s) from other Flows, and beyond!
readTime: 3 min read
---

# Triggers

> A trigger defines the event that starts your flow. This could be from an internal or external activity, such as
> changes to data, logins, errors, incoming webhooks, cron jobs, operations from other flows, or even the click of a
> button within the Data Studio.

:::tip Before You Begin

Please be sure to read the overview documentation on [Flows](/configuration/flows).

:::

## Event Hook

![Event Hooks](https://cdn.directus.io/docs/v9/configuration/flows/triggers/triggers-20220603A/event-hook-20220602A.webp)

Event Hooks are triggered by events within the platform. The logic is based on [Custom API Hooks](/extensions/hooks).
Any data generated by the event will be nested in the `$trigger`.

- **Type** — Choose the type of event hook:
  - [Filter (Blocking)](#filters) — This pauses the transaction and passes the `payload` to your flow, allowing you to
    validate or transform `payload` or even prevent the event transaction.
  - [Action (Non-Blocking)](#actions) — Actions do not block the event. A non-blocking action is mostly useful for
    completing tasks in response to an event, without modifying the event or slowing the API.
- **Scope** — Set the types of events that trip this trigger.
- **Collections** — Set the collections _whose events_ trip this trigger.
- **Response Body** — This is optional. Its also only for **Filter (Blocking)** events. Defines data to replace the
  event's original `payload`. Choose to return:
  - **Data of Last Operation** — Replaces event `payload` with value from `$last`.
  - **All Data** — Replaces event `payload` with the entire data chain.
  - **Other** — Replaces event `payload` with value from an `<operationKey>`.

::: tip Events with Multiple Items

If you create items in a single request, the Flow will trigger once for each and every item. If you create three items,
the flow runs three separate times. On each run, just one item will be in the payload.

:::

### Filters

<!-- ![Blocking Events](image.webp) -->

A Filter will halt the event transaction, copy the event `payload` into the flow, let the whole flow run,
**_optionally_** replace the original `payload` by configuring **Response Body**, then resume the event's transaction to
the database.

For example, let's say you configure the scope to be `item.create`.

- A request to create an item is sent to Directus.
- The create item event halts.
- The event's `payload` is copied into the `$trigger` of the flow.
- The flow runs.
- _Optional:_ If you defined a **Response Body**, this replaces the event's `payload`.
- The event transaction is committed or cancelled, based on your flow's logic.

:::tip Response Body

If no **Response Body** is configured, the original payload will not be modified, but you'd still have the ability to
cancel the transaction.

:::

:::tip Cancelling Transactions

To completely cancel a transaction, you'll need to throw an error within a
[script operation](/configuration/flows/operations.md#script) or end the flow on a
[failure path](/configuration/flows#control-flow).

:::

### Actions

<!-- ![Non-Blocking Events](image.webp) -->

An Action lets the event commit its transaction to the database without waiting for the flow to finish. Therefore,
Actions give you a more performant API, but you have no ability to validate or transform the payload before the
transaction is committed to the database. However, a copy of the `payload` is still added into `$trigger` to use as
desired.

For example, let's imagine once more that you configure the scope to be `item.create`.

- A request to create an item is sent to Directus.
- The create item event is transacted.
- The event's `payload` is copied into the `$trigger` of the flow.
- The flow runs.

To recap, Filters let you modify the original `payload` of an event but block the API until the flow finishes. Actions
still provide the `payload` to the flow, but don't let you modify it before transaction; so you get a faster API but no
control over the event transaction.

## Webhook

![Webhook](https://cdn.directus.io/docs/v9/configuration/flows/triggers/triggers-20220603A/webhook-20220602A.webp)

Triggers on an incoming HTTP request to: `/flows/trigger/:this-webhook-trigger-id` which you can copy from the webhook
trigger panel.

- **Method** — Choose whether the flow will be triggered by a `GET` or `POST` request from the dropdown.
- **Asynchronous** — Toggle whether or not the trigger responds asynchronously.
- **Response Body** — Optional. Defines data to return as a response. Choose to return:
  - **Data of Last Operation** — Responds with value from `$last`.
  - **All Data** — Responds with the entire data chain.
  - **Other** — Responds with value from an `<operationKey>`.

:::tip Response Body

If no data is defined in **Response Body**, the response is empty.

:::

:::tip Asynchronous

If **Asynchronous** is enabled, the flows system will immediately resolve/respond to the request without returning a
**Response Body**, which frees up the API immediately. If it is disabled, the flows system will wait for the flow to
finish and return whatever value is in **Response Body**. This slows the API, but lets you send data.

:::

## Schedule

![Schedule a Cron Job](https://cdn.directus.io/docs/v9/configuration/flows/triggers/triggers-20220603A/cron-20220602A.webp)

This trigger enables you to create data at scheduled intervals, via
[6-point cron job syntax](https://github.com/node-cron/node-cron#cron-syntax).

- **Interval** — Set the cron job interval to schedule when the flow triggers.

## Another Flow

![Another Flow](https://cdn.directus.io/docs/v9/configuration/flows/triggers/triggers-20220603A/another-flow-20220602A.webp)

This trigger executes by the [trigger flow](/configuration/flows/operations#another-flow) operation, allowing you to
chain flows.

- **Response Body** — Optional. Defines data to return and append under the `<operationKey>` of
  [trigger flow](/configuration/flows/operations#another-flow) operation that tripped the trigger. Choose to return:
  - **Data of Last Operation** — Responds with value from `$last`.
  - **All Data** — Responds with the entire data chain.
  - **Other** — Responds with value from an `<operationKey>`.

:::tip Flows for-loops

If you pass an array to this trigger, it will run once for each item in the array.

:::

## Manual

![Manual](https://cdn.directus.io/docs/v9/configuration/flows/triggers/triggers-20220603A/manual-20220602A.webp)

This Trigger starts your flow on a manual click of a button within the Data Studio. When you use this trigger, a
**Flows** menu containing a button will appear in the sidebar of the specified collection page(s) and/or its item pages.

The manual trigger must take in item ID(s) before you can click it. So on the collection page, the button will be
_grayed out_ until you select some number of items. From the item page, the current item's ID is passed in
automatically. These item IDs are passed in to `$trigger`.

- **Collections** — Choose the Collection(s) to add the button to.
- **Location** — Choose to display the button on the [Item Page](/app/content.md#item-page),
  [Collection Page](/app/content.md#collection-page), or both.
- **Asynchronous** — Toggle whether or not the Flow executes asynchronously.
- **Collection Page (Requires Selection)** — Toggle whether a selection is required in the Collection Page to trigger.

After the operation runs, a toast notification will appear in your [sidebar](/app/overview.md#4-sidebar) indicating
whether the flow ran successfully.

:::tip Asynchronous

If **Asynchronous** is enabled, the flows system will immediately allow you to use the manual trigger button again to
send more requests. If it is disabled, you will have to wait until the flow completes to use it again.

:::
