> ## Documentation Index
> Fetch the complete documentation index at: https://flywheel.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# New Event Trigger
> Start an agent run when a specific user event occurs in your application
## How New Event Trigger Works
When a user performs an action that matches your trigger configuration, the agent immediately starts a run for that user. New Event triggers respond to specific user actions or events that occur in your application and are ideal for real-time, context-aware responses to user behavior.
Unlike workflow event triggers which follow a fixed action sequence, agent event triggers pass the full event and user context to the language model, which then reasons about what tools to call and how to act.
## Configuration
Select the specific event name that should start an agent run. Examples: `user_signed_up`, `subscription_created`, `purchase_completed`, `trial_started`.
The complete event data that triggered the agent run.
Unique database identifier for this event.
Unique external identifier for this event.
The name of the event that triggered the run.
ISO datetime when the event occurred.
ISO datetime when the event was created in the system.
Internal Flywheel user identifier associated with the event.
Your company's external user identifier, if available.
Organization identifier.
Anonymous identifier for the user, if available.
The source of the event (e.g., web, mobile, API).
The location where the event occurred, if available.
The type of event: `track` or `identify`.
Schema identifier for the event structure, if applicable.
Contains all event-specific data and custom properties specific to your application and event type.
Comprehensive user information for the user who triggered the event.
Unique user identifier.
Organization identifier.
Your company's external user identifier.
User's primary email address.
User's primary phone number.
User's first name.
User's last name.
ISO datetime when the user was created.
ISO datetime when the user was last updated.
Current subscription status: `incomplete`, `incomplete_expired`, `trialing`, `active`, `past_due`, `canceled`, `unpaid`, `paused`, `inactive`.
Payment processor used: `stripe` or `paddle`.
Monthly recurring revenue from this user.
Lifetime value of the user.
ISO datetime of user's first payment.
ISO datetime of user's next scheduled payment.
ISO datetime when subscription will be cancelled (if applicable).
User's preferred contact method.
Additional contact information and preferences.
Customer Success Manager information assigned to this user.
Custom user properties you've defined.
## Use Cases
**New User Onboarding**
```
Event: user_signed_up
Agent behavior: Evaluate user profile, check account fit, send personalized onboarding guidance, assign CSM if enterprise tier
```
**Trial Conversion Outreach**
```
Event: trial_started
Agent behavior: Check activation milestones, search for prior engagement, send contextual onboarding email or Slack message
```
**High-Value Purchase Follow-up**
```
Event: purchase_completed
Agent behavior: Analyze purchase context, generate personalized thank-you email, notify account owner via Slack
```
**Churn Risk Response**
```
Event: subscription_canceled
Agent behavior: Gather cancellation context, check usage patterns via Find Event, create Intercom ticket for retention team
```
## Best Practices
**Choose Stable Event Names**
* Use consistent, predictable event names that match your tracking plan
* Ensure required event properties exist if your tools or prompt rely on them
* Test with realistic payloads before enabling Live mode
**Consider Event Frequency**
* Some events may fire multiple times for the same user
* Use your agent prompt to describe how to handle duplicate or repeated events
* Consider whether the agent should check for recent runs before acting
**Monitor Performance**
* Track trigger activation rates and run completion in the Runs tab
* Review agent reasoning and tool selection for quality
* Iterate on prompts based on real run data