---
title: Flow Event Trigger
slug: flow-event-trigger
docTags: 
createdAt: 2025-08-11T11:13:48.000Z
---

Flow Event Triggers enable playbooks to listen for and respond to events emitted by other playbooks using the **Emit Event** native action. This creates a powerful mechanism for inter-playbook communication, allowing you to build complex, distributed workflows where one playbook can trigger another based on specific conditions or outcomes.

## Overview

Flow Event Triggers work in conjunction with the **Emit Event** native action to create event-driven workflows:

- **Emit Event Action**: Generates events during playbook execution with custom data
- **Flow Event Trigger**: Listens for specific events and initiates playbooks when those events are emitted

This pattern enables you to:

- Decouple workflows into smaller, focused playbooks
- Create reusable playbook components
- Build event-driven architectures
- Trigger multiple playbooks from a single event
- Process events asynchronously without blocking the emitting playbook

## Key Benefits

- **Inter-Playbook Communication**: Enable playbooks to communicate and trigger each other
- **Asynchronous Processing**: Emitted events are processed asynchronously, allowing the emitting playbook to continue execution
- **Event-Driven Architecture**: Build complex workflows based on event patterns
- **Reusability**: Create reusable playbook components that can be triggered by multiple sources
- **Scalability**: Events are distributed across scaled services for parallel processing

## Creating a Flow Event Trigger

To create a Flow Event Trigger:

1. From the **Add** section, drag and drop **Flow Event** to the playbook canvas.
2. Click on the added Flow Event trigger to view the **Trigger** configuration panel.

::Image[]{src="https://app.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/-YwlGXKUDtiYV4sZQAOWQ_flow-event.png" size="30" width="456" height="809" darkWidth="456" darkHeight="809" position="center" indent="2" showCaption="false"}

## Configuring the Flow Event Trigger

### Step 1: Select Flow Event Type

Choose between **Existing flow event** or **Create flow event**:

### Option A: Existing Flow Event

1. Select **Existing flow event** from the toggle.
2. In the **Flow Event** dropdown, choose from a list of already created flow events.
   - The dropdown shows all available flow events (sensors) in your tenant
   - Each event shows its title (human-readable name)
3. Optionally add or edit a **Description** to document the trigger's purpose.

**Note:** When selecting an existing flow event, the event data schema is already defined. You can configure conditions but cannot modify the event data structure.

### Option B: Create Flow Event

1. Select **Create flow event** from the toggle.
2. Configure the following fields:
   - **Flow Event Title**: Enter a human-readable name for the event (e.g., "Email Processed", "Incident Escalated"). This is displayed in the UI.
   - **Flow Event Name**: A unique identifier for the event (auto-generated from the title, but can be edited). Must contain only letters, numbers, and underscores (A-Z, a-z, 0-9, \_).
   - **Description**: (Optional) Add a description explaining the purpose of the event.

**Important:** The **Flow Event Name** (sensor name) must match exactly between the Emit Event action and the Flow Event Trigger. This is the key used to match events.

### Step 2: Configure Event Data Schema (Create Flow Event Only)

If you selected **Create flow event**, you need to define the event data schema:

1. Click **Configure** to open the event data configuration dialog.
2. In the **Event Data** section, define the properties for the event data:
   - Click **Add Property** to add a new data property.
   - Configure each property with:
     - **Property Name**: The key used to access this data in the triggered playbook
     - **Property Type**: Choose from:
       - **String**: Text values
       - **Number**: Numeric values (default: `0`)
       - **Boolean**: `True` or `False` values
       - **Object**: Nested objects (add properties within the object)
       - **Array**: Arrays of values (define the item type)
       - **Attachment**: File attachments

**Note:** The event data schema defines what data can be emitted and received. Both the Emit Event action and Flow Event Trigger must use compatible schemas.

### Step 3: Configure Conditions (Optional)

1. In the configuration dialog, you can add conditions to filter when the playbook should be triggered.
2. Conditions evaluate the event data and determine if the playbook should run.
3. Click **Apply** to save your configuration.

For more information about **Emit Event** native action, see [Emit Event](https://docs.swimlane.com/emit-event-native-action) documentation.

## How Flow Event Triggers Work

### Event Matching

Flow Event Triggers match events based on the **sensor name** (Flow Event Name), not the title. The matching process works as follows:

1. **Emit Event Action** emits an event with:
   - `sensorName`: The unique identifier (Flow Event Name)
   - `eventData`: The data payload to send
2. **Flow Event Trigger** listens for events matching:
   - The sensor name must match exactly between Emit Event and Flow Event Trigger
   - Optional conditions can further filter events
3. When a match is found, the triggered playbook starts execution with the event data.

### Event Processing

- **Asynchronous Execution**: Events are processed asynchronously. The playbook emitting the event continues execution immediately without waiting for triggered playbooks to complete.
- **Concurrent Processing**: Multiple playbooks can be triggered by the same event, and they execute concurrently.
- **No Order Guarantee**: Due to distributed processing across scaled services, there is no guarantee of execution order for multiple triggered playbooks.
- **Event Distribution**: Events are distributed across scaled services for parallel processing.

## Flow Event Trigger Outputs

When a Flow Event Trigger fires, it provides event data that can be accessed in your playbook.

### Event Data Structure

The event data is available via `$event.data` and contains the properties defined in the event data schema. Additionally, you can access event metadata:

- `$event.data`: The event data payload (properties defined in the event schema)
- `$event.type`: Event type (always `"flow"` for flow events)
- `$event.action`: Event action (always `"emit"` for flow events)
- `$event.fqn`: Fully qualified event name (format: `sensorName.type`)
- `$event.timestamp`: Timestamp when the event was received (milliseconds since epoch)
- `$event.sensor.name`: The sensor name (Flow Event Name)
- `$event.sensor.tags`: Sensor tags (if any)
- `$event.agent.name`: Name of the agent that processed the event
- `$event.agent.tags`: Agent tags (if any)
- `$event.tags`: Combined sensor and agent tags

### Accessing Event Data in Playbooks

You can access event data in your playbook actions using the `$event.data` prefix:

**Examples:**

```text
# Access event data properties
$event.data.propertyName
$event.data.emailSender
$event.data.incidentId

# Access nested object properties
$event.data.user.name
$event.data.user.email

# Access array elements (in loops)
$event.data.items[0]
$loop.value  # when looping over $event.data.items

# Access event metadata
$event.sensor.name
$event.timestamp
```

**Note:** Property names must match exactly as defined in the event data schema. Property names are case-sensitive.

## Key Considerations

- **Sensor Name Matching**: The **Flow Event Name** (sensor name) must match exactly between the Emit Event action and the Flow Event Trigger. The title can be different, but the name must match.
- **Event Data Schema**: When creating a new flow event, define the event data schema in the trigger configuration. The Emit Event action must emit data that matches this schema.
- **Asynchronous Processing**: Events are processed asynchronously. The emitting playbook continues execution immediately.
- **No Order Guarantee**: Multiple playbooks triggered by the same event may execute in any order.
- **Event Persistence**: Events are processed in real-time. If a playbook is not running or disabled when an event is emitted, it will not be triggered.
- **Maximum event chain depth**: By default, Turbine limits event chaining (event -> playbook -> emit event -> playbook) to 10 levels.
- **Conditions**: Use conditions in the Flow Event Trigger to filter events based on data values before triggering the playbook.

## Example Scenarios

### Example 1: Processing Emails with Event Correlation

**Scenario:** A playbook processes incoming emails and emits an event when an email matches certain criteria. Another playbook listens for this event and saves the email data to a database.

**Configuration:**

**Playbook A (Email Processor):**

1. Add an **Emit Event** action after processing emails.
2. Configure the Emit Event:
   - **Sensor Name**: `email-processed`
   - **Event Data**:
     - `sender`: Email sender address
     - `subject`: Email subject
     - `content`: Email content
     - `timestamp`: Email timestamp

**Playbook B (Email Storage):**

1. Add a **Flow Event** trigger.
2. Select **Existing flow event** and choose `email-processed`.
3. Configure conditions (optional): Only trigger if `$event.data.sender` contains `"@company.com"`.
4. Add actions to save email data:
   - Use **Create Record** action
   - Map `$event.data.sender` to record field
   - Map `$event.data.subject` to record field
   - Map `$event.data.content` to record field

**Result:** When Playbook A processes an email, it emits an event. Playbook B listens for this event and automatically saves the email data to a database record.

### Example 2: Incident Escalation Chain

**Scenario:** When an incident is escalated, emit an event that triggers multiple playbooks: one to notify stakeholders, another to update external systems, and a third to create a follow-up task.

**Configuration:**

**Playbook A (Incident Escalation):**

1. Add an **Emit Event** action after escalating an incident.
2. Configure the Emit Event:
   - **Sensor Name**: `incident-escalated`
   - **Event Data**:
     - `incidentId`: Incident tracking ID
     - `priority`: New priority level
     - `escalatedBy`: User who escalated
     - `reason`: Escalation reason

**Playbook B (Notification):**

1. Add a **Flow Event** trigger for `incident-escalated`.
2. Add **Send Notification** action to notify stakeholders.
3. Use `$event.data.incidentId` and `$event.data.priority` in the notification.

**Playbook C (External System Update):**

1. Add a **Flow Event** trigger for `incident-escalated`.
2. Add **HTTP** action to update external ticketing system.
3. Use `$event.data.incidentId` in the API payload.

**Playbook D (Follow-up Task):**

1. Add a **Flow Event** trigger for `incident-escalated`.
2. Add **Create Record** action to create a follow-up task.
3. Use `$event.data.incidentId` and `$event.data.reason` in the task.

**Result:** When an incident is escalated, all three playbooks execute concurrently to handle notifications, external updates, and task creation.

### Example 3: Conditional Event Processing

**Scenario:** Emit an event with order data, but only trigger downstream playbooks for high-value orders.

**Configuration:**

**Playbook A (Order Processing):**

1. Add an **Emit Event** action after processing an order.
2. Configure the Emit Event:
   - **Sensor Name**: `order-processed`
   - **Event Data**:
     - `orderId`: Order identifier
     - `amount`: Order total amount
     - `customerId`: Customer identifier
     - `items`: Array of order items

**Playbook B (High-Value Order Handler):**

1. Add a **Flow Event** trigger for `order-processed`.
2. Configure conditions:
   - `$event.data.amount` **greater than** `1000`
3. Add actions to handle high-value orders:
   - Send notification to sales manager
   - Create priority fulfillment task
   - Update CRM system

**Result:** Only orders with amounts greater than $1000 trigger the high-value order handling playbook.

## Best Practices

- **Consistent Naming**: Use consistent naming conventions for Flow Event Names to avoid mismatches. Consider using a naming pattern like `domain-action` (e.g., `email-processed`, `incident-escalated`).
- **Event Data Schema Design**: Design event data schemas carefully to include all necessary information. Avoid including sensitive data unless necessary.
- **Use Conditions**: Leverage conditions in Flow Event Triggers to filter events and reduce unnecessary playbook executions.
- **Document Events**: Add descriptions to flow events to document their purpose and expected data structure.
- **Error Handling**: Consider error handling in triggered playbooks, as they execute asynchronously and may fail independently.
- **Event Versioning**: If you need to change an event schema, consider creating a new flow event with a new name rather than modifying existing ones, to avoid breaking existing playbooks.
- **Testing**: Test event flows thoroughly, especially when multiple playbooks are triggered by the same event.
- **Monitoring**: Monitor playbook run history to ensure events are being received and processed correctly.

## Troubleshooting

- **Playbook Not Triggering:**
  - Verify the Flow Event Name (sensor name) matches exactly between Emit Event and Flow Event Trigger
  - Check that the playbook is published and enabled
  - Verify conditions are not filtering out all events
  - Review playbook run history for errors
- **Event Data Not Accessible:**
  - Verify property names match exactly (case-sensitive)
  - Check that the event data schema includes the properties you're trying to access
  - Ensure the Emit Event action is sending data in the expected format
- **Multiple Playbooks Not Executing:**
  - Verify all playbooks have the correct Flow Event Name configured
  - Check that all playbooks are published and enabled
  - Review conditions in each trigger to ensure events aren't being filtered out
- **Event Order Issues:**
  - Remember that events are processed asynchronously with no order guarantee
  - If order matters, use sequential processing or add sequence numbers to event data
- **Schema Mismatch:**
  - Ensure the event data schema matches between Emit Event and Flow Event Trigger
  - When creating a new flow event, define the schema in the trigger first, then use the same schema in the Emit Event action