# Triggers & Events This document defines how [**Triggers**](https://app.quickreply.ai/data-source/webhooks) and [**Events**](https://app.quickreply.ai/data-source/events) work in QuickReply.ai and how they should be designed to build scalable, low-error Journeys and Campaigns. *** ### What Is a [Trigger](https://app.quickreply.ai/data-source/webhooks)? A [**Trigger**](https://app.quickreply.ai/data-source/webhooks) is an incoming webhook action sent to QuickReply.ai via a **POST request**. #### Key Characteristics * Receives raw data (JSON payload) * Has **no filters or business logic** * Cannot trigger messages on its own * Can power **multiple Events** {% hint style="info" %} A Trigger is only a data ingestion mechanism. No action can be performed in QuickReply.ai without an Event. {% endhint %} *** ### What Is an [Event](https://app.quickreply.ai/data-source/events)? An [**Event**](https://app.quickreply.ai/data-source/events) is a logical layer created on top of a [Trigger](https://app.quickreply.ai/data-source/events). #### Key Characteristics * Uses identifiers and attributes from the payload * Applies filters and conditions * Acts as the **only entry point** to: * Journeys * Campaigns * Can be reused across multiple modules {% hint style="warning" %} **Important:** No action can be performed in QuickReply.ai without an Event. {% endhint %} *** ### Trigger → Event → Journey / Campaign Flow #### Relationship Model * **Trigger (1 → many) Events** * **Event (1 → many) Journeys** * **Event (1 → many) Campaigns** *** ### Visual Architecture
*** ### Example Webhook Payload A CRM sends the following payload to a QuickReply.ai webhook: ```json { "event_name": "new_lead_created", "lead_type": "hot", "lead_details": { "name": "Utkarsh", "phone": "+919634687270", "age": 24, "orders": [ { "id": 123, "amount": 1400 }, { "id": 456, "amount": 999 } ] } } ``` This payload is received by a **Trigger**.

How it looks like on QuickReply.ai

*** ### Why Triggers Alone Have No Value Triggers: * Do not segment users * Do not evaluate conditions * Do not trigger Journeys or Campaigns To perform **any action**, an Event must: * Identify *what* happened (`event_name`) * Qualify *who* it happened to (`lead_type`) * Decide *when* execution should start *** ### Event Design Patterns #### ❌ Pattern 1: One Event + Journey-Level Filters (Not Recommended) **Structure** * One Trigger → One Event → Multiple Journeys * Filtering done inside Journeys or via conditional branches **Issues** * Manual filter setup for every journey * High risk of human error * Analytics are mixed * Hard to scale > This pattern introduces operational dependency and should be avoided. *** #### ✅ Pattern 2: Multiple Events with Pre-Filled Filters (Recommended) **Structure** * One Trigger → Multiple Events * Filters defined once at Event level **Example Events** * Hot Lead Created → `lead_type = hot` * Warm Lead Created → `lead_type = warm` * Cold Lead Created → `lead_type = cold` **Benefits** * Clean journey configuration * Faster execution * Independent analytics per Event * Lower error probability *** ### Pro Tip: Centralise Logic at the Event Level Because filters are defined on **Events**, not on Journeys: * Updating an Event automatically updates: * All connected Journeys * All connected Campaigns * No need to edit individual journeys * Changes reflect in real time This is especially useful when: * CRM logic changes * Lead qualification rules evolve * Multiple journeys depend on the same Event *** ### Handling Multiple Business Actions in One Trigger A single webhook may contain multiple business actions: * `new_lead_created` * `lead_abandoned` * `lead_converted` #### Recommended Setup **Trigger** * `CRM – Events` **Events** * Hot Lead Created * `event_name = new_lead_created` * `lead_type = hot`
* Warm Lead Created * `event_name = new_lead_created` * `lead_type = warm`
* Cold Lead Created * `event_name = new_lead_created` * `lead_type = cold`
* Hot Lead Abandoned * `event_name = lead_abandoned` * `lead_type = hot`
* Warm Lead Abandoned * `event_name = lead_abandoned` * `lead_type = warm`
* Cold Lead Abandoned * `event_name = lead_abandoned` * `lead_type = cold`
This keeps: * Triggers minimal * Events explicit * Journeys reusable and clean

Triggers and Events as shown in Journeys

*** ### Recommended Best Practices Checklist * Use **fewer Triggers** * Create **many specific Events** * Avoid journey-level filtering * Reuse Events across Journeys and Campaigns * Treat Events as the single source of truth > **Triggers ingest data. Events define meaning. Journeys execute logic.** *** ### Decision Framework: When to Create a New Event Use this table as a reference guideline: | Scenario | Create New Event? | Reason | | ---------------------------------- | ----------------- | ----------------------------- | | Different `event_name` | ✅ Yes | Different business action | | Different `lead_type` | ✅ Yes | Different segmentation | | Different analytics needed | ✅ Yes | Clean reporting | | Only message content differs | ❌ No | Same Event, different Journey | | Same logic reused in many journeys | ❌ No | Reuse Event | *** ### Anti-Patterns to Avoid #### ❌ Too Many Triggers * Harder to maintain * Duplicated webhook logic * Poor visibility #### ❌ Journey-Level Filtering * High human dependency * Inconsistent behaviour * Difficult debugging #### ❌ Generic Events Example: `CRM Event Received`\ This provides no operational clarity and defeats the Event layer. *** ### Naming Conventions (Strongly Recommended) Clear naming is critical once you scale beyond a few Events. #### Trigger Naming **Format** ``` – ``` **Examples** * `CRM – Events` * `Shopify – Order Webhooks` * `Backend – User Lifecycle` **Why** * Identifies *where* data is coming from * Prevents duplicate triggers for the same system > Triggers should never encode business logic in their names. *** #### Event Naming **Format** ``` - ``` **Examples** * Lead Created - Hot * Lead Abandoned - Warm * Lead Converted - Cold * Order Placed - High Value **Rules** * Use human-readable names * Reflect filters applied inside the Event * Avoid technical field names in Event titles > If a non-technical user cannot understand the Event name, it is poorly named. *** #### Journey Naming **Format** ``` – ``` **Examples** * Lead Nurture – Hot Lead Created * Re-Engagement – Warm Lead Abandoned * Upsell Flow – High Value Order Placed **Why** * Makes analytics self-explanatory * Easier debugging and audits ### Journey Usage Example #### Journey: Warm Lead Re-Engagement * **Start Condition:** Event → *Warm Lead Abandoned* * **Actions:** * WhatsApp reminder after 30 minutes * Follow-up message after 24 hours * Escalation to agent if no response **Result** * No filters inside Journey * Clean analytics * Easy to replicate for Hot / Cold leads *** ### Analytics & Reporting Impact Because Events are granular: * Conversion rates per lead type are visible * Drop-offs can be isolated * Campaign vs Journey performance is comparable > Event-level separation directly improves reporting accuracy. ### Final Architectural Summary **Design Once, Scale Forever** * Few Triggers * Many explicit Events * Simple Journeys * Centralised logic * Reliable analytics > If your Events are correct, everything else becomes easy. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.quickreply.ai/product-modules/journeys/data-sources/triggers-and-events.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.