Workflow Triggers

Triggers are the events that start your workflows. Choose the right trigger to ensure your automations fire at exactly the right moment in your user’s journey.

How to Choose the Right Trigger

Goal	Best Trigger	Why
Welcome new users	Contact identified (`Contact.Identified`)	Fires when a contact is first identified
Reward completions	Gameplay ended (`Gameplay.Ended`)	Fires when a user finishes an experience
Qualify leads	Data captured (Qualified entries only) (`Gameplay.DataCapturedQualified`)	Only fires for qualified entries
Celebrate winners	Prize Awarded (`Prize.Awarded`)	Fires immediately when a prize is won
Manage lists	Contact added to List (`Contact.ListAdded`)	Fires when a contact joins a specific list
Reward coupon activity	Coupon Issued / Coupon Redeemed	Fires when a coupon is issued or redeemed
Survey completion	Survey Completed (`Survey.Completed`)	Fires when a survey is completed
Challenge progress	Challenge completed and related Challenge triggers	Fires on challenge, goal, milestone, streak, or run events
Receive external data	Webhook Received (`Webhook.Received`)	Fires when an external system sends data to your webhook URL

Contact Triggers

Events related to contact creation, updates, and list management.

Trigger	When It Fires	Data Available	Perfect For
Contact.Identified	New contact is created or identified	Contact profile, source	Welcome sequences, onboarding
Contact.PropertyUpdated	Any contact field is modified	Old/new values, updated fields	Re-segmentation, personalization
Contact.Verified.Sso	Contact verifies via SSO login	Verification details, provider	Account activation, access grants
Contact.ListAdded (Contact added to List)	Contact joins a specific list	List name, contact details	List-specific communications

Example: Welcome New Users

Trigger: Contact.Identified
├── Contact Filter: First time visitor
│   ├── Success: Send welcome email
│   └── Add to "New Users" list
└── Award: 50 welcome points

Gameplay Triggers

Events that fire during user interactions with your experiences.

Trigger	When It Fires	Data Available	Perfect For
Gameplay.Action	Any action taken in experience	Action type, timestamp, context	Engagement scoring, behavior tracking
Gameplay.Ended	User completes or exits experience	Completion status, duration, `score`, `correctCount`	Completion rewards, follow-ups, score-based branching
Data captured (Including disqualified) (`Gameplay.DataCaptured`)	Form submitted (all entries)	Form fields, qualification status	Lead generation, data collection
Data captured (Qualified entries only) (`Gameplay.DataCapturedQualified`)	Form submitted (qualified only)	Validated form data	Sales notifications, CRM sync
Gameplay.ReceiptValidationSuccess	Receipt upload approved	Receipt details, validation score	Purchase rewards, loyalty points
Gameplay.ReceiptValidationRejected	Receipt upload rejected	Rejection reason (`event.rejection_reason`), uploaded file	Fraud prevention, user guidance, branching on rejection cause
Gameplay.TreasureHuntCheckpointCompleted	Checkpoint reached in treasure hunt	Checkpoint details, progress	Progressive rewards, engagement
Gameplay.UploadApproved	User-generated content approved	Upload details, approval notes	UGC workflows, social sharing
Gameplay.UploadRejected	User-generated content rejected	Rejection reason, moderation notes	Content guidelines, re-submission
Gameplay.LiveSurveyQuestionAsked	Question submitted in live Q&A	Question text, user details	Real-time moderation, engagement
Gameplay.LiveSurveyQuestionApproved	Q&A question approved for display	Approved question, moderator	Live event management, curation
Gameplay.LiveSurveyQuestionRejected	Q&A question rejected	Rejection reason, question text	Content moderation, user feedback

Gameplay ended fires as soon as the player finishes the game. On cards where the entry form appears after gameplay (for example Photo Frame, where the form opens after the photo is created), Gameplay ended can fire before the player submits the form, so the workflow may run without the form details (for example email) or for players who never submit.If the workflow depends on the form details (sending a coupon or email, syncing to a CRM/Braze, adding to a list), use Data captured instead, which fires when the form is submitted.

Gameplay score variables

When Gameplay.Ended fires, the trigger payload includes score data you can reference in downstream steps (filters, decisions, email/SMS templates, webhooks):

Variable	Type	Description
`score`	number \| null	Numeric score for the gameplay. `null` for card types that don’t have a score concept.
`correctCount`	number \| null	Number of correct answers (or completion count) for gameplay types that support it. `null` otherwise.

Score availability by card type:

Quiz, Trivia, Predictive, Swiper — both score and correctCount are populated
Treasure Hunt — score is populated; correctCount is the completed checkpoint count
Memory Challenge — score is populated; correctCount is null
Other card types — both values are null

Use these variables to branch on performance (for example, only send a “high score” email when score exceeds a threshold) or to award bonus loyalty points proportional to correctCount.

Example: Lead Qualification Flow

Trigger: Gameplay.DataCapturedQualified
├── Contact Filter: Company size > 100 employees
│   ├── Success: 
│   │   ├── Webhook to Salesforce CRM
│   │   └── Tag: "Enterprise Lead"
│   └── Fallback:
│       ├── Add to "SMB Nurture" email sequence
│       └── Tag: "SMB Lead"

Example: Route rejected receipts by reason

When a receipt validation is rejected, the rejection reason is exposed as event.rejection_reason. You can reference it in split decisions, filters, and Liquid templates (for example, email content):

Trigger: Gameplay.ReceiptValidationRejected
├── Split Decision: event.rejection_reason contains "duplicate"
│   ├── Success: Send "We've already received this receipt" email
│   └── Fallback: Send generic "Receipt couldn't be validated" email

In an email template you can surface a friendly message based on the reason:

{% if event.rejection_reason contains "duplicate" %}
  It looks like this receipt has already been submitted.
{% else %}
  We couldn't validate your receipt. Please upload a clearer photo.
{% endif %}

Coupon Triggers

Events related to coupon issuance and redemption. Use these when you need automations that react to coupons themselves (including coupons issued from a workflow Issue coupon step), not only prizes.

Trigger	When it fires	Perfect for
Coupon Issued (`Coupon.Issued`)	A coupon is issued to a contact	Issue confirmations, reminder lists, contact property updates, loyalty awards
Coupon Redeemed (`Coupon.Redeemed`)	A coupon is redeemed	Redemption tracking, post-redeem messaging, list updates

Filters and data

Both coupon triggers support these filters:

Coupon is
Coupon is in
Coupon is not
Coupon is not in

Each run is tied to the contact who was issued or redeemed the coupon. Event data fields:

Field	Description
`id`	Event id
`timestamp`	When the issue or redeem happened
`coupon_id`	Coupon id
`coupon_offer_id`	Coupon offer id
`coupon_name`	Coupon name
`barcode`	Barcode value
`barcode_type`	Barcode type
`pin`	PIN, when present
`redeem_location_name`	Redeem location name

Pair the trigger with actions such as Add to list, Update, Send email, or Send HTTP request. Award points only appears if the workspace has the Loyalty Programs feature.

Example: Reminder list after coupon issue

Trigger: Coupon Issued
├── Filter: Coupon is <specific coupon>
├── Add to list: "Coupon issued — send reminder"
└── Update: set last_coupon_issued

Example: Follow up on redemption

Trigger: Coupon Redeemed
├── Add to list: "Redeemed"
├── Remove from list: "Coupon issued — send reminder"
└── Send email: redemption thank-you

Survey Triggers

Trigger	When it fires	Perfect for
Survey Completed (`Survey.Completed`)	A contact completes a survey	Follow-up sequences, list membership, contact property updates

Filters and data

Survey Completed supports these filters:

Survey is
Survey is in
Survey is not
Survey is not in

A workflow can also be scoped to one survey under Scope → Optional Scope → Survey. Each run is tied to the contact who completed the survey. Event data fields:

Field	Description
`id`	Event id
`timestamp`	When the survey was completed
`site_id`	Hub (site) id
`submission_id`	Submission id
`site_name`	Hub (site) name
`survey_id`	Survey id
`survey_name`	Survey name
`form_values`	Map of form field values

Pair it with actions such as Add to list, Update, and Send email.

Example: Survey completion follow-up

Trigger: Survey Completed
  Scope: Optional Scope → Survey (specific survey)
├── Add to list: "Survey respondents"
├── Update: set survey_completed = true
└── Send email: thank-you / next steps

Challenge Triggers

Events related to challenge progress, completion, and streak management. Filter these triggers to scope automations precisely.

Trigger	When It Fires	Perfect For
Challenge.Completed	A contact finishes a challenge	Completion rewards, badge issuance, follow-up sequences
Challenge.GoalCompleted	A contact completes a goal within a challenge	Goal-tier rewards, progress notifications
Challenge.GoalMilestoneCompleted	A contact reaches a milestone inside a goal	Progressive rewards, encouragement messages
Challenge.RunExpired	A challenge run ends without completion	Re-engagement campaigns, retry prompts
Challenge.StreakBroken	A contact’s streak resets	Win-back outreach, streak recovery offers

Available filters

Challenge trigger filters are scoped per event:

Challenge — available on every Challenge trigger
Goal — only on Challenge.GoalCompleted and Challenge.GoalMilestoneCompleted
Milestone — only on Challenge.GoalMilestoneCompleted

Prize Triggers

Events related to prize awards and winner management.

Trigger	When It Fires	Data Available	Perfect For
Prize.Awarded	User wins a prize	Prize details, winner info	Winner notifications, fulfillment
Prize.ExtraDataCaptured	Additional winner data collected	Extra form fields, prize context	Prize claim verification, shipping

Example: Winner Notification System

Trigger: Prize.Awarded
├── Contact Filter: Prize value > $50
│   ├── Success: Send premium winner email + SMS
│   └── Fallback: Send standard winner email
├── Add to List: "Prize Winners"
└── Webhook: Notify fulfillment system

Card Triggers

Events related to card interactions and engagement.

Trigger	When It Fires	Data Available	Perfect For
Card.CoverClicked	User clicks on card cover/preview	Card details, click context	Engagement tracking, interest scoring

Example: Interest Tracking

Trigger: Card.CoverClicked
├── Contact Update: Increment "card_clicks" counter
├── Tag: "Engaged User"
└── Decision: If clicks > 5 this week
    └── Success: Add to "Highly Engaged" list

Loyalty Triggers

Events related to loyalty program activities.

Trigger	When It Fires	Data Available	Perfect For
Loyalty.PointsAwarded	Points credited to account	Points amount, earning reason	Award confirmations, tier checks
Loyalty.PointsRedeemed	Points spent on redemption	Points spent, redemption details	Redemption confirmations, inventory
Loyalty.TierAdded	User promoted to new tier	New tier, previous tier	Tier upgrade celebrations, benefits
Loyalty.TierRemoved	User demoted from tier	Removed tier, current tier	Re-engagement campaigns, retention

Example: Tier Upgrade Celebration

Trigger: Loyalty.TierAdded
├── Contact Filter: New tier = "Gold"
│   ├── Success: 
│   │   ├── Send gold tier welcome email
│   │   ├── Issue 500 bonus points
│   │   └── Send exclusive discount code
└── Add to List: "Gold Members"

Webhook Triggers

Events triggered by external systems sending data to your workflow’s webhook URL.

Trigger	When It Fires	Data Available	Perfect For
Webhook Received (`Webhook.Received`)	External HTTP request hits your webhook URL	Webhook payload fields (defined by your schema)	Third-party integrations, external system events, custom automations

How webhook triggers work

When you select Webhook.Received as your trigger, Komo generates a unique webhook URL for your workflow. External systems can send HTTP POST requests to this URL to trigger the workflow. You can define a JSON schema for your expected webhook payload. This schema tells the workflow editor what fields to expect, so you can reference them in your workflow steps using Liquid template variables.

Using webhook data in workflow steps

Once you define a schema for your webhook payload, the fields become available as Liquid template variables under the webhook namespace. For example, if your webhook payload includes user_id and amount fields, you can reference them as:

{{ webhook.user_id }}
{{ webhook.amount }}

Nested fields use dot notation. For example, a payload with a nested address.city field can be referenced as {{ webhook.address.city }}.

Example: External purchase sync

Trigger: Webhook.Received
  Schema: { user_id: string, amount: number, product: string }
├── Contact Filter: webhook.amount > 100
│   ├── Success:
│   │   ├── Award loyalty points (webhook.amount × 2)
│   │   └── Send "VIP Purchase" email
│   └── Fallback:
│       └── Award loyalty points (webhook.amount)
└── Contact Update: Set "last_purchase" = webhook.product

Setting up a webhook trigger

Create a new workflow and select Webhook Received as the trigger event
A unique webhook slug is generated for your workflow — this forms your webhook URL. You can regenerate the slug at any time if the URL needs to be rotated.
Send a few sample requests to the webhook URL to capture draft events (see below), or define a request schema by hand using JSON Schema format to describe the expected payload structure
Use the schema fields as Liquid variables in your workflow actions (e.g., email templates, contact updates, filters)

Capturing draft events

Before publishing your workflow, send sample requests to the webhook URL to capture real payloads as draft events. Komo stores the 10 most recent requests received against the trigger, so you can inspect them in the workflow editor and confirm the data looks right. Draft events make it much faster to wire up downstream steps because you can see exactly what each external system sends — including nested objects and arrays — without having to read the third-party docs first.

Auto-generating a request schema

Once a draft event has been captured, you can generate a JSON schema from any sample payload with one click. Komo inspects the structure of the request body and produces a matching JSON Schema definition for you. This means you usually don’t need to write the schema by hand — just send a representative request, pick the draft event, and generate the schema. You can then edit the generated schema if you need to make fields optional, tighten types, or add validation rules.

Schema validation and limits

To keep webhook triggers safe and performant, request schemas have a few limits:

Limit	Value
Maximum schema size	64 KB
Maximum nesting depth	32 levels
Maximum number of regex patterns (`pattern` / `patternProperties`)	50
Maximum regex source length	256 characters
Maximum regex quantifier upper bound (e.g. `{0,n}`)	256

An empty schema ({}) or no schema at all is treated as “accept any payload” and skips these checks. Schemas must be valid JSON Schema (comments and trailing commas aren’t allowed).

Supported regex patterns

Komo blocks regex constructs that can enable catastrophic backtracking or stall the runtime. When you use pattern or patternProperties, the following are not supported:

Backreferences (\1, \k<name>)
Lookbehind assertions ((?<=…), (?<!…))
Atomic groups ((?>…))
Conditionals ((?(…)…))
Inline comments ((?#…))
Anchors \A, \G, \Z, and \z (use ^ and $ instead)
More than one broad wildcard repetition (for example two .* / .+ in the same pattern)
Unbounded repetition (*, +, {n,}) applied to a group that contains alternation (|)
Unbounded repetition applied to a group that already contains unbounded repetition
Adjacent unbounded repetitions (for example a*b*)

Lookahead ((?=…), (?!…)) and non-capturing groups ((?:…)) are supported. Komo validates the schema when you save it and surfaces a clear error for the exact path that’s invalid (for example, $.properties.email.pattern).

Webhook delivery requirements

When external systems send requests to your webhook URL, Komo enforces the following limits and behaviors:

Request format

Method: POST only — other methods return 405
Body: JSON object (must be Content-Type: application/json). Arrays and primitives are rejected with 400 Invalid JSON Object
Maximum payload size: 512 KB. Larger requests return 413 Payload Too Large

Authentication

Webhooks are unauthenticated by default. If you add one or more webhook keys to a trigger, every request must include a matching Authorization: Bearer <token> header. Requests without a valid key return 401 Unauthorized.

Rate limits

Each webhook is rate-limited per 60-second window. Limits depend on your plan and the trigger mode:

Mode	Default limit (requests / minute)
Draft (testing)	20
Live	1,000 (varies by plan tier)

When the limit is exceeded, requests return 429 Rate limit exceeded with the following headers:

X-RateLimit-Limit — your current limit
Retry-After — seconds until the window resets (always 60)

Schema validation at delivery time

If you define a request schema, every payload is validated against it. Requests that fail validation return 422 and are not delivered to your workflow. Payloads that pass validation return 202 Accepted along with a trackingId you can use to correlate the request to a workflow run.

Response codes summary

Status	Meaning
`202`	Accepted — workflow has been queued
`400`	Invalid request (bad slug, malformed JSON, missing content)
`401`	Missing or invalid `Authorization` header
`404`	Webhook not found, inactive, or expired draft
`413`	Payload exceeds 512 KB
`422`	Payload failed schema validation
`429`	Rate limit exceeded
`500`	Internal error (transient — safe to retry)

Advanced Trigger Strategies

1. Trigger Stacking

Use multiple related triggers for comprehensive coverage:

# Welcome sequence with multiple entry points
Trigger 1: Contact.Identified (new users)
Trigger 2: Contact.Verified.Sso (returning users)
Both → Same welcome workflow with different paths

2. Qualification Layering

Combine broad triggers with specific filters:

Trigger: Gameplay.DataCaptured (all submissions)
├── Contact Filter: Email contains company domains
│   └── Success: Route to B2B workflow
└── Fallback: Route to B2C workflow

3. Time-Based Follow-ups

Chain triggers for timed sequences:

Initial: Prize.Awarded
├── Immediate: Send winner notification
├── After 24h: Send claim reminder (if not claimed)
└── After 7 days: Send final reminder

Troubleshooting Triggers

Common Issues

Problem	Likely Cause	Solution
Trigger not firing	Incorrect scope configuration	Verify workflow scope matches trigger source
Too many executions	Overly broad trigger conditions	Add specific filters to narrow scope
Missing data	Trigger fired before data available	Add delay or data validation checks
Duplicate workflows	Multiple workflows with same trigger	Use exclusion filters or combine workflows

Testing Tips

Start with broad triggers - Use Gameplay.Action to see all events
Add logging - Use webhook actions to log trigger data
Test with real data - Use actual user interactions, not simulated events
Monitor execution volume - Check Workflow Runs for unexpected patterns

Best Practices

✅ Do This

Be specific - Use qualified triggers when possible (DataCapturedQualified vs DataCaptured)
Add context filters - Narrow scope with contact properties or gameplay data
Plan for scale - Consider execution volume for broad triggers
Document trigger purpose - Name workflows clearly to indicate trigger intent

❌ Avoid This

Don’t use overly broad triggers without filters (Contact.PropertyUpdated without field specification)
Don’t stack identical triggers - Combine similar workflows instead
Don’t ignore data availability - Ensure required data exists when trigger fires
Don’t skip testing - Always verify triggers fire as expected

What’s Next?

Browse workflow actions → - Explore actions to pair with these triggers
Back to workflows guide → - Return to main workflows documentation

Need help choosing the right trigger? Contact support at [email protected]

​Workflow Triggers

​How to Choose the Right Trigger

​Contact Triggers

​Example: Welcome New Users

​Gameplay Triggers

​Gameplay score variables

​Example: Lead Qualification Flow

​Example: Route rejected receipts by reason

​Coupon Triggers

​Filters and data

​Example: Reminder list after coupon issue

​Example: Follow up on redemption

​Survey Triggers

​Filters and data

​Example: Survey completion follow-up

​Challenge Triggers

​Available filters

​Prize Triggers

​Example: Winner Notification System

​Card Triggers

​Example: Interest Tracking

​Loyalty Triggers

​Example: Tier Upgrade Celebration

​Webhook Triggers

​How webhook triggers work

​Using webhook data in workflow steps

​Example: External purchase sync

​Setting up a webhook trigger

​Capturing draft events

​Auto-generating a request schema

​Schema validation and limits

​Supported regex patterns

​Webhook delivery requirements

​Request format

​Authentication

​Rate limits

​Schema validation at delivery time

​Response codes summary

​Advanced Trigger Strategies

​1. Trigger Stacking

​2. Qualification Layering

​3. Time-Based Follow-ups

​Troubleshooting Triggers

​Common Issues

​Testing Tips

​Best Practices

​✅ Do This

​❌ Avoid This

​What’s Next?

Workflow Triggers

How to Choose the Right Trigger

Contact Triggers

Example: Welcome New Users

Gameplay Triggers

Gameplay score variables

Example: Lead Qualification Flow

Example: Route rejected receipts by reason

Coupon Triggers

Filters and data

Example: Reminder list after coupon issue

Example: Follow up on redemption

Survey Triggers

Filters and data

Example: Survey completion follow-up

Challenge Triggers

Available filters

Prize Triggers

Example: Winner Notification System

Card Triggers

Example: Interest Tracking

Loyalty Triggers

Example: Tier Upgrade Celebration

Webhook Triggers

How webhook triggers work

Using webhook data in workflow steps

Example: External purchase sync

Setting up a webhook trigger

Capturing draft events

Auto-generating a request schema

Schema validation and limits

Supported regex patterns

Webhook delivery requirements

Request format

Authentication

Rate limits

Schema validation at delivery time

Response codes summary

Advanced Trigger Strategies

1. Trigger Stacking

2. Qualification Layering

3. Time-Based Follow-ups

Troubleshooting Triggers

Common Issues

Testing Tips

Best Practices

✅ Do This

❌ Avoid This

What’s Next?