Event Webhooks

Event webhooks are triggered by specific conversation events rather than dialog actions. They provide different payload structures and are designed for monitoring, analytics, and automated responses based on conversation flow events.

info

For common webhook configurations like verifying origin and IP whitelisting, see the Webhooks Overview.

Event Types

Event webhooks support three distinct event types, each with its own timing and use cases:

First Message

Triggered when a user starts a new conversation session. This event fires only once per session and can be useful for:

• User onboarding and welcome sequences
• Session initialization and tracking
• Setting up user context or preferences
• Analytics and user engagement tracking

Pre Message

Triggered before processing each user message. This event allows you to:

• Implement custom message filtering or moderation
• Add preprocessing logic to user inputs
• Set dynamic context variables before AI processing
• Log incoming messages for analytics

Post Message

Triggered after processing each user message and generating a response. This event enables:

• Response post-processing and customization
• Analytics and conversation tracking
• Integration with external systems after response generation
• Custom logging and monitoring

Payload Structure

Event webhooks use different payload structures compared to dialog webhooks, optimized for their specific event-driven nature.

First message and Pre message webhook Payload

{
  "channel": "test",
  "session_id": "8563dcdf-64ef-4de2-a5ca-b96e0557e4e8",
  "desk_id": "d3d08940-f0ef-42e0-993c-1bea065dcqwe",
  "integration_id": "",
  "brain_id": "d3d08940-f0ef-42e0-993c-1bea065dcqwe",
  "lang": "en",
  "context": {
    "user": {
      "user_id": "test-O44vJC-TuXiJXh8hkXvlZ",
      "display_name": "Visitor 2020",
      "verified": false
    },
    "sys-unknown_counter": 0,
    "sys-session": "8563dcdf-64ef-4de2-a5ca-b96e0557e4e8",
    "sys-brain_id": "d3d08940-f0ef-42e0-993c-1bea065dcqwe",
    "sys-channel": "web",
    "sys-business": "open",
    "sys-user_message_counter": 3
  },
  "timestamp": 1761045302529,
  "input": {
    "text": "hi",
    "attachments": []
  },
  "business_closed": false
}

Post Message Payload

{
  "event_type": "post_message",
  "session_id": "00d2ff33-706e-4a2c-8544-df6c9d0c1ecf",
  "brain_id": "d3d08940-f0ef-42e0-993c-1bea065dcqwe",
  "channel": "web",
  "timestamp": 1699531250000,
  "input": {
    "text": "Hello, I need help with my order",
    "attachments": []
  },
  "output": {
    "responses": [
      {
        "type": "text",
        "text": "I'd be happy to help you with your order. Can you provide your order number?"
      }
    ],
    "intents": [
      {
        "intent": "order_inquiry",
        "confidence": 0.95
      }
    ],
    "entities": [
      {
        "entity": "order",
        "value": "order",
        "start": 32,
        "end": 37,
        "confidence": 0.9
      }
    ]
  },
  "context": {
    "sys-channel": "web",
    "sys-user_message_counter": 3,
    "current_intent": "order_inquiry"
  }
}

Payload Reference

Common Fields

All event webhook payloads include these common fields:

Property	Type	Description
session_id	string	Unique identifier for the conversation session
brain_id	string	The ID of the AI Agent
channel	string	Channel name ("web", "whatsapp", etc.)
desk_id	string	The ID of the current environment
integration_id	string	The ID of the current integration
timestamp	integer	Unix timestamp in milliseconds when event occurred
context	object	Current context variables

Event-Specific Fields

Pre / First Message Webhooks

Property	Type	Description
input	object	User input
business_closed	boolean	If we are outside business hours

Post Message Events

Property	Type	Description
input	object	User input that triggered the event
intents	object	Intents triggered
entities	object	Entities identified
User message counter	number	The number of user messages
output	object	AI Agent response and processing results

Input Object

Property	Type	Description
text	string	The text typed by the user
attachments	array	Array of media attachments

Response Handling

Event webhooks have different response requirements compared to dialog webhooks:

First Message & Pre Message

• Context updates: Can return context updates that will be applied before processing
• No response generation: Cannot generate direct responses to users
• Session modification: Can modify session state and variables (such as live instructions)
• Change the user input: Can alter the input of the user for its processing

Example Response:

{
  "context": {
    "user_crm_level": "platinum",
    "live_instructions": "The user's name is George. He is a VIP customer."
  }
}

Post Message

• Change response: Can modify the AI Agent's response (already generated)
• Context updates: Can update context for future messages
• Analytics: Can be used for logging and external system integration

Example Response:

{
  "context": {
    "last_intent": "order_inquiry"
  }
}

Configuration

Event webhooks are configured differently from dialog webhooks:

1. Global Configuration: Set at the AI Agent level, not per dialog node
2. Event Selection: Choose which events to subscribe to
3. URL per Event: Can use different URLs for different event types
4. Batch Processing: Option to batch multiple events in a single call