> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.komo.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Triggers

> Complete guide to all workflow triggers with use cases and implementation examples

# 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

```yaml theme={null}
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 | Completion rewards, follow-ups        |
| **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, uploaded file    | Fraud prevention, user guidance       |
| **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     |

### Example: Lead Qualification Flow

```yaml theme={null}
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"
```

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

```yaml theme={null}
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

```yaml theme={null}
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

```yaml theme={null}
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

```yaml theme={null}
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

1. Create a new workflow and select **Webhook.Received** as the trigger event
2. A unique **webhook slug** is generated for your workflow — this forms your webhook URL
3. Optionally define a **request schema** using JSON Schema format to describe the expected payload structure
4. Use the schema fields as Liquid variables in your workflow actions (e.g., email templates, contact updates, filters)

## Advanced Trigger Strategies

### 1. Trigger Stacking

Use multiple related triggers for comprehensive coverage:

```yaml theme={null}
# 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:

```yaml theme={null}
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:

```yaml theme={null}
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

1. **Start with broad triggers** - Use `Gameplay.Action` to see all events
2. **Add logging** - Use webhook actions to log trigger data
3. **Test with real data** - Use actual user interactions, not simulated events
4. **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 →**](/integrations-automation/workflows/actions) - Explore actions to pair with these triggers
* [**Back to workflows guide →**](/integrations-automation/workflows) - Return to main workflows documentation

Need help choosing the right trigger? Contact support at [support@komo.tech](mailto:support@komo.tech)