Triggers

Overview

Triggers enable event-driven automation in KaireonAI. When a customer event occurs — a transaction, a profile update, a behavioral signal — a trigger can automatically enroll the customer in a journey, fire a real-time recommendation, call an external webhook, or update customer attributes.

How Triggers Work

Event Source → Trigger Rule → Condition Evaluation → Action Execution

An event arrives from a connected data source (streaming connector, API call, or schema update)
The trigger rule matches events by type and optional filters
Conditions are evaluated to determine if the trigger should fire
The configured action is executed

Runtime Behavior

When an event is received, the engine performs the following sequence:

Event matching — All active trigger rules with a matching eventType are retrieved, ordered by priority (descending).
Condition evaluation — For each matching trigger, the condition object is evaluated against the event payload. Conditions support nested all (AND) and any (OR) groups with field-level operators (eq, neq, gt, gte, lt, lte, in, exists).
Cooldown check — If the trigger has a cooldownMs value greater than zero, the engine checks whether the same trigger has already fired for this customer within the cooldown window. If it has, the trigger is skipped.
Action dispatch — If all conditions pass and the cooldown has not been exceeded, the configured action is dispatched (journey enrollment, recommend call, webhook POST, or attribute update).
Audit logging — Every trigger firing is recorded in the audit log with the trigger ID, customer ID, event type, and action taken.

Multiple triggers can match the same event. They are evaluated in priority order, and each fires independently as long as its own conditions and cooldown are satisfied.

Event Types

Triggers listen for events from your connected data sources:

Event Type	Description
`outcome.recorded`	An outcome (impression, click, conversion) was recorded via the Respond API
`customer.created`	A new customer record was inserted into a schema table
`customer.updated`	An existing customer record was modified
`segment.entered`	A customer entered a segment (met the segment criteria)
`segment.exited`	A customer exited a segment (no longer meets criteria)
`journey.completed`	A customer completed a journey
`offer.expired`	An offer reached its end date
`budget.exhausted`	An offer’s budget allocation was fully consumed

Action Types

Action Type	Description
`enroll_journey`	Enroll the customer in a specified journey
`fire_recommend`	Execute a Decision Flow and deliver the result immediately
`webhook`	Send an HTTP POST to an external URL with event data
`update_attribute`	Update one or more customer attributes in a schema table

enroll_journey

{
  "actionType": "enroll_journey",
  "config": {
    "journeyId": "jrn_loan_nurture",
    "deduplication": "skip_if_active"
  }
}

The deduplication option prevents enrolling a customer who is already active in the same journey. Options: skip_if_active (default), restart, allow_multiple.

fire_recommend

{
  "actionType": "fire_recommend",
  "config": {
    "decisionFlowId": "df_realtime_offers",
    "channelId": "ch_push",
    "limit": 1,
    "deliverImmediately": true
  }
}

webhook

{
  "actionType": "webhook",
  "config": {
    "url": "https://api.yourcompany.com/events/handle",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer {{secret.webhook_token}}"
    },
    "bodyTemplate": {
      "customerId": "{{event.customerId}}",
      "eventType": "{{event.type}}",
      "triggerId": "{{trigger.id}}"
    }
  }
}

update_attribute

{
  "actionType": "update_attribute",
  "config": {
    "schemaId": "schema_customer_profile",
    "updates": [
      { "field": "last_event_date", "value": "{{event.timestamp}}" },
      { "field": "event_count", "expression": "event_count + 1" }
    ]
  }
}

Cooldown Mechanics

Each trigger has a configurable cooldown period (cooldownMs, in milliseconds) to prevent rapid re-firing for the same customer. How cooldown works:

When a trigger fires for a customer, the engine records the firing timestamp.
On the next matching event for the same customer, the engine checks if now - lastFiredAt < cooldownMs.
If the cooldown has not elapsed, the trigger is silently skipped for that customer. The event is not queued for later — it is dropped.
The cooldown is per-customer, per-trigger. Customer A’s cooldown does not affect Customer B.

Cooldown Value	Behavior
`0`	No cooldown; fires on every matching event
`60000` (1 min)	At most once per minute per customer
`3600000` (1 hr)	At most once per hour per customer
`86400000` (24 hr)	At most once per day per customer

Without a cooldown, high-frequency events (e.g., page views, transaction streams) can cause a trigger to fire hundreds of times per customer. Always set an appropriate cooldown.

Priority

When multiple triggers match the same event, they are executed in priority order:

Priority	Value Range	Description
Critical	90-100	Compliance and regulatory triggers
High	70-89	Revenue-critical automations
Medium	40-69	Standard engagement triggers
Low	1-39	Background/informational triggers

Worked Example

A retail bank wants to trigger a real-time recommendation whenever a customer completes a purchase over $500:

Event arrives

The Respond API records an outcome.recorded event for customer cust_78 with outcomeType: "conversion" and metadata.amount: 750.

Trigger matches

The engine finds the “High-Value Purchase” trigger with eventType: "outcome.recorded" and priority: 75.

Condition evaluates

The trigger’s condition is checked: { "all": [{ "field": "metadata.amount", "operator": "gt", "value": 500 }] }. The event’s amount (750) is greater than 500, so the condition passes.

Cooldown check

The trigger has cooldownMs: 86400000 (24 hours). The last firing for cust_78 was 3 days ago, so the cooldown has elapsed.

Action dispatches

The fire_recommend action executes Decision Flow df_cross_sell with channelId: "ch_push" and maxOffers: 1. The customer receives a personalized push notification with a cross-sell offer.

Field Reference

Field	Type	Required	Default	Description
`name`	string	Yes	—	Trigger name (min 1 character)
`description`	string	No	`""`	Human-readable description
`eventType`	string	Yes	—	Event type to listen for (see Event Types table)
`condition`	object	No	`{}`	Nested condition groups with `all`/`any` logic and field-level operators
`actionType`	enum	Yes	—	One of: `enroll_journey`, `fire_recommend`, `webhook`, `update_attribute`
`actionConfig`	object	No	`{}`	Action-specific configuration (see Action Types section)
`priority`	number	No	`50`	Execution priority (0-100, higher = first)
`cooldownMs`	number	No	`0`	Minimum milliseconds between firings for the same customer
`status`	enum	Auto	`active`	Trigger status: `active`, `paused`, `disabled`

Condition Operators

Operator	Description	Example
`eq`	Equals	`{ "field": "eventType", "operator": "eq", "value": "conversion" }`
`neq`	Not equals	`{ "field": "channel", "operator": "neq", "value": "sms" }`
`gt`	Greater than	`{ "field": "amount", "operator": "gt", "value": 500 }`
`gte`	Greater than or equal	`{ "field": "score", "operator": "gte", "value": 0.8 }`
`lt`	Less than	`{ "field": "age", "operator": "lt", "value": 30 }`
`lte`	Less than or equal	`{ "field": "count", "operator": "lte", "value": 5 }`
`in`	Value in list	`{ "field": "tier", "operator": "in", "value": ["gold", "platinum"] }`
`exists`	Field exists	`{ "field": "email", "operator": "exists" }`

Creating a Trigger

Navigate to Triggers

Go to Studio > Triggers in the sidebar.

Click Create Trigger

Click the + New Trigger button.

Name and describe

Enter a name and description for the trigger.

Select event type

Choose the event type that will activate this trigger.

Define conditions (optional)

Add filter conditions to narrow when the trigger fires (e.g., metadata.amount > 500).

Select action type

Choose the action: enroll in journey, fire recommendation, call webhook, or update attribute.

Configure action

Fill in the action-specific configuration (journey ID, Decision Flow, webhook URL, etc.).

Set cooldown and priority

Configure the cooldown period and execution priority.

Save and enable

Save the trigger. Toggle it to enabled when ready.

API Reference

Create a Trigger

POST /api/v1/triggers
Content-Type: application/json

Request body:

{
  "name": "High-Value Purchase Cross-Sell",
  "description": "Fire real-time recommendation after a purchase over $500",
  "eventType": "outcome.recorded",
  "condition": {
    "all": [
      { "field": "metadata.amount", "operator": "gt", "value": 500 },
      { "field": "outcomeType", "operator": "eq", "value": "conversion" }
    ]
  },
  "actionType": "fire_recommend",
  "actionConfig": {
    "decisionFlowId": "df_cross_sell",
    "channelId": "ch_push",
    "limit": 1,
    "deliverImmediately": true
  },
  "cooldownMs": 86400000,
  "priority": 75
}

Response (201 Created):

{
  "id": "trg_high_value_purchase",
  "name": "High-Value Purchase Cross-Sell",
  "eventType": "outcome.recorded",
  "actionType": "fire_recommend",
  "cooldownMs": 86400000,
  "priority": 75,
  "status": "active",
  "createdAt": "2026-03-10T14:30:00Z",
  "updatedAt": "2026-03-10T14:30:00Z"
}

List Triggers

GET /api/v1/triggers?status=active&eventType=outcome.recorded&limit=50&offset=0

Query parameters:

Parameter	Type	Default	Description
`status`	string	all	Filter by trigger status
`eventType`	string	all	Filter by event type
`limit`	number	50	Page size (max 200)
`offset`	number	0	Pagination offset

Update a Trigger

PUT /api/v1/triggers/:id

Delete a Trigger

DELETE /api/v1/triggers/:id

Enable/Disable a Trigger

Use the update endpoint to change a trigger’s status:

PUT /api/v1/triggers/:id
Content-Type: application/json

{ "status": "paused" }

Allowed status transitions: active to paused or disabled, paused to active or disabled, disabled to active.

Get Started

Deploy & Operate

Runbooks

Data Platform

Decisioning Studio

Execute & Optimize

Intelligence

Platform & Security

Integrations

Reports

Release Notes

Overview

How Triggers Work

Runtime Behavior

Event Types

Action Types

enroll_journey

fire_recommend

webhook

update_attribute

Cooldown Mechanics

Priority

Worked Example

Field Reference

Condition Operators

Creating a Trigger

API Reference

Create a Trigger

List Triggers

Update a Trigger

Delete a Trigger

Enable/Disable a Trigger

Next Steps

Journeys

Runs

Get Started

Deploy & Operate

Runbooks

Data Platform

Decisioning Studio

Execute & Optimize

Intelligence

Platform & Security

Integrations

Reports

Release Notes

​Overview

​How Triggers Work

​Runtime Behavior

​Event Types

​Action Types

​enroll_journey

​fire_recommend

​webhook

​update_attribute

​Cooldown Mechanics

​Priority

​Worked Example

​Field Reference

​Condition Operators

​Creating a Trigger

​API Reference

​Create a Trigger

​List Triggers

​Update a Trigger

​Delete a Trigger

​Enable/Disable a Trigger

​Next Steps

Journeys

Runs

Overview

How Triggers Work

Runtime Behavior

Event Types

Action Types

enroll_journey

fire_recommend

webhook

update_attribute

Cooldown Mechanics

Priority

Worked Example

Field Reference

Condition Operators

Creating a Trigger

API Reference

Create a Trigger

List Triggers

Update a Trigger

Delete a Trigger

Enable/Disable a Trigger

Next Steps