Flow Event Trigger

15 min

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:

From the Add section, drag and drop Flow Event to the playbook canvas.

Click on the added Flow Event trigger to view the Trigger configuration panel.

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

Select Existing flow event from the toggle.

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)

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

Select Create flow event from the toggle.

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:

Click Configure to open the event data configuration dialog.

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)

In the configuration dialog, you can add conditions to filter when the playbook should be triggered.

Conditions evaluate the event data and determine if the playbook should run.

Click Apply to save your configuration.

For more information about Emit Event native action, see Emit Event 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:

Emit Event Action emits an event with:

sensorName: The unique identifier (Flow Event Name)

eventData: The data payload to send

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

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:

# 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.

Maximum Event Chain Depth: By default, Turbine limits event chaining (event -> playbook -> emit event -> playbook) to 10 levels.

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.

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):

Add an Emit Event action after processing emails.

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):

Add a Flow Event trigger.

Select Existing flow event and choose email-processed.

Configure conditions (optional): Only trigger if $event.data.sender contains "@company.com".

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):

Add an Emit Event action after escalating an incident.

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):

Add a Flow Event trigger for incident-escalated.

Add Send Notification action to notify stakeholders.

Use $event.data.incidentId and $event.data.priority in the notification.

Playbook C (External System Update):

Add a Flow Event trigger for incident-escalated.

Add HTTP action to update external ticketing system.

Use $event.data.incidentId in the API payload.

Playbook D (Follow-up Task):

Add a Flow Event trigger for incident-escalated.

Add Create Record action to create a follow-up task.

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):

Add an Emit Event action after processing an order.

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):

Add a Flow Event trigger for order-processed.

Configure conditions:

$event.data.amount greater than 1000

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