Chat Webhook Events Analysis

This document provides an extensive analysis of the webhooks triggered throughout the chat system (chatFunctions.ts). It details the events, their payloads, and when they are triggered.

General Overview

The chat system supports webhooks to notify external systems about the state and progress of a chat session. Webhooks can be defined at the template level or passed dynamically when starting a chat.

There are two distinct webhook mechanisms:

1. Standard Chat Webhooks: Notifications sent during the lifecycle of a standard chat (Initiated, Processing, Generating, Completed, User Message).
2. Webhook Only Chat: A specialized chat type where the system processes inputs and immediately calls a webhook, expecting an external system to handle the response.

Standard Chat Webhooks

These webhooks are triggered for standard chats (e.g., ChatType.TEMPLATE, ChatType.INLINE).

Common Payload Structure

All standard webhook events share a common JSON structure. The data field varies by event type.

{
  "metadata": {
    "userId": "string",       // ID of the user who created the chat
    "organizationId": "string", // Organization ID
    "templateId": "string",   // Template ID used
    "chatId": "string",       // Unique Chat ID
    "messageNumber": number,  // Index of the message related to the event (optional)
    "externalId": "string",   // External ID provided during chat creation (optional)
    "publicTokenId": "string" // Public token ID if applicable (optional)
  },
  "type": "string",           // The specific event type (e.g., "STATUS_CHANGE", "RESULT")
  "eventType": "string",      // Same as type, included for convenience
  "timestamp": number,        // Unix timestamp (ms)
  "status": "string",         // Current chat status (e.g., "initiated", "processing", "generating", "completed")
  "data": { ... }             // Event-specific data
}

Event Types

1. Chat Initiated (INITIATED)

• Trigger: When a new chat session is successfully created via startChat.
• Webhook Event Type: STATUS_CHANGE
• Chat Status: initiated
• Data Payload:

  {
  	"templateId": "string"
  }

• When to use: To log that a new chat has started or to initialize a corresponding record in an external system.

2. User Message (USER_MESSAGE)

• Trigger:
  • Immediately after chat initiation (with initial input values).
  • When a user sends a new message via sendMessageToChat.
• Webhook Event Type: USER_MESSAGE
• Chat Status: undefined (This event is independent of the chat status machine)
• Data Payload:

  {
  	"message": "string", // The content of the user's message
  	"role": "user",
  	"attachments": [
  		// Optional list of file attachments
  		{
  			"fileId": "string",
  			"fileName": "string"
  		}
  	]
  }

• When to use: To capture user inputs and maintain a transcript of the conversation.

3. Processing (PROCESSING)

• Trigger: When the system begins preparing to generate a response. This happens before file loading and context compilation.
• Webhook Event Type: STATUS_CHANGE
• Chat Status: processing
• Data Payload:

  {
  	"inputs": {} // Currently empty
  }

• When to use: To indicate to the user that the system has received the request and is working on it (e.g., showing a spinner).

4. Generating (GENERATING)

• Trigger: Just before the AI model is invoked to generate the response. At this point, all files and context have been loaded.
• Webhook Event Type: STATUS_CHANGE
• Chat Status: generating
• Data Payload: {} (Empty object)
• When to use: To know that the AI generation phase has started.

5. Completed (COMPLETED)

• Trigger: When the AI generation has successfully finished.
• Webhook Event Type: RESULT
• Chat Status: completed
• Data Payload:

  {
  	"response": "string" // The full text response from the AI
  }

• When to use: To receive the final answer from the AI. This is the most critical event for capturing the output.

---

Webhook Only Chat (ChatType.WEBHOOK_ONLY)

This is a special mode where the Gen8 system acts as a proxy/pre-processor.

• Trigger: When generateInitialResponse is called for a chat with type: "webhook-only".
• Mechanism: The system gathers all inputs, resolves the template, downloads file attachments, and then makes a single POST request to the configured webhook URL.
• Payload:

  {
    "inputs": { ... },          // Parsed input values
    "resolvedTemplate": "string", // The prompt template with variables resolved
    "responseWebhookUrl": "string", // URL for the external system to post the reply back to
    "attachments": ["url1", "url2"], // Download URLs for files
    "txtFiles": ["content1", "content2"] // Text content of text-based files
  }

• Expected Behavior: The external system receives this payload, processes it, and then sends a POST request to the responseWebhookUrl with the response content.

Responding to Webhook Only Chat

To reply to the chat, the external system must POST to the responseWebhookUrl:

• Method: POST
• Body:

  {
  	"content": "string", // The response message
  	"attachments": [], // Optional attachments
  	"artifacts": {}, // Optional artifacts
  	"requestedInput": {} // Optional requested input definition
  }

Summary of Events Flow

1. Start Chat:
   • INITIATED event sent.
   • USER_MESSAGE event sent (with initial inputs).
2. Generate Response (Standard Chat):
   • PROCESSING event sent.
   • (System loads files, compiles context)
   • GENERATING event sent.
   • (AI generates response)
   • COMPLETED event sent (with result).
3. User Replies:
   • USER_MESSAGE event sent.
   • (Cycle repeats from step 2).