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

Inputs

Trigger Event · string · required

Select the specific event name that should start an agent run. Examples: user_signed_up, subscription_created, purchase_completed, trial_started.

Outputs

event · object · required

The complete event data that triggered the agent run.

Show Event Properties

event.id · string · required

Unique database identifier for this event.

event.event_id · string · required

Unique external identifier for this event.

event.event_name · string · required

The name of the event that triggered the run.

event.timestamp · string · required

ISO datetime when the event occurred.

event.created_at · string · required

ISO datetime when the event was created in the system.

event.org_user_id · string · required

Internal Flywheel user identifier associated with the event.

event.org_assigned_user_id · string

Your company’s external user identifier, if available.

event.org_id · number · required

Organization identifier.

event.anonymous_id · string

Anonymous identifier for the user, if available.

event.event_source · string

The source of the event (e.g., web, mobile, API).

event.event_location · string

The location where the event occurred, if available.

event.event_type · enum

The type of event: track or identify.

event.schema_id · string

Schema identifier for the event structure, if applicable.

event.custom_properties · object · required

Contains all event-specific data and custom properties specific to your application and event type.

org_user · object · required

Comprehensive user information for the user who triggered the event.

Show User Properties

org_user.id · string · required

Unique user identifier.

org_user.org_id · number · required

Organization identifier.

org_user.org_assigned_user_id · string

Your company’s external user identifier.

org_user.primary_email · string

User’s primary email address.

org_user.primary_phone · string

User’s primary phone number.

org_user.first_name · string

User’s first name.

org_user.last_name · string

User’s last name.

org_user.created_at · string · required

ISO datetime when the user was created.

org_user.updated_at · string · required

ISO datetime when the user was last updated.

org_user.subscription_status · enum · required

Current subscription status: incomplete, incomplete_expired, trialing, active, past_due, canceled, unpaid, paused, inactive.

org_user.payment_processor · enum · required

Payment processor used: stripe or paddle.

org_user.mrr · number

Monthly recurring revenue from this user.

org_user.ltv · number

Lifetime value of the user.

org_user.first_payment_date · string

ISO datetime of user’s first payment.

org_user.next_payment_date · string

ISO datetime of user’s next scheduled payment.

org_user.cancels_at · string

ISO datetime when subscription will be cancelled (if applicable).

org_user.primary_contact_method · string

User’s preferred contact method.

org_user.contact_info · object · required

Additional contact information and preferences.

org_user.csm · object · required

Customer Success Manager information assigned to this user.

org_user.custom_properties · object · required

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