> For the complete documentation index, see [llms.txt](https://docs.quickreply.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.quickreply.ai/product-modules/journeys/data-sources/triggers-and-events.md).

# 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

<figure><img src="/files/G7GU0ClE6cUdm8oYHtyx" alt=""><figcaption></figcaption></figure>

***

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

<figure><img src="/files/9O6RmxylikProH3nnl6A" alt=""><figcaption><p>How it looks like on QuickReply.ai</p></figcaption></figure>

***

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

  <figure><img src="/files/BoyhA7E0o7XE0zeS8yeB" alt=""><figcaption></figcaption></figure>
* Warm Lead Created

  * `event_name = new_lead_created`
  * `lead_type = warm`

  <figure><img src="/files/dPLqcRCaATmh1MtFposF" alt=""><figcaption></figcaption></figure>
* Cold Lead Created
  * `event_name = new_lead_created`
  * `lead_type = cold`

<figure><img src="/files/tnbNfeUiGyHzXo7MqcZS" alt=""><figcaption></figcaption></figure>

* Hot Lead Abandoned

  * `event_name = lead_abandoned`&#x20;
  * `lead_type = hot`

  <figure><img src="/files/s0gD7Vk9hbagNOugL94n" alt=""><figcaption></figcaption></figure>
* Warm Lead Abandoned

  * `event_name = lead_abandoned`
  * `lead_type = warm`

  <figure><img src="/files/l1jyrVLsfvymxWrSdSYo" alt=""><figcaption></figcaption></figure>
* Cold Lead Abandoned

  * `event_name = lead_abandoned`
  * `lead_type = cold`

  <figure><img src="/files/pXE3s9kNJcVCgzAnHX90" alt=""><figcaption></figcaption></figure>

This keeps:

* Triggers minimal
* Events explicit
* Journeys reusable and clean

<figure><img src="/files/VxPndCtLNoqb7beYI3Ya" alt="" width="563"><figcaption><p>Triggers and Events as shown in Journeys</p></figcaption></figure>

***

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

```
<Source System> – <Payload Scope>
```

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

```
<Business Action> - <Qualifier (optional)>
```

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

```
<Objective> – <Event Name>
```

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