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`	Fires when contact is first created
Reward completions	`Card.Completed` or `Gameplay.Ended`	Fires when user finishes experience
Qualify leads	`Gameplay.DataCapturedQualified`	Only fires for qualified entries
Celebrate winners	`Prize.Awarded`	Fires immediately when prize is won
Manage lists	`Contact.ListAdded`	Fires when contact joins specific list
Receive external data	`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 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
Gameplay.DataCaptured	Form submitted (all entries)	Form fields, qualification status	Lead generation, data collection
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 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, Memory Challenge — both score and correctCount are populated
Treasure Hunt — 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 %}

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

​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?