Webhook Events

Complete reference for all AlonChat webhook event types and their payloads

Webhook Events#

AlonChat sends real-time HTTP POST notifications when events occur in your agent. This guide covers all 13 event types and their payloads.

Event Types#

leads.submit#

Trigger: User submits a contact or lead form during a conversation.

Payload:

json

{
  "event": "leads.submit",
  "agent_id": "agent-uuid",
  "timestamp": "2026-03-15T10:30:00Z",
  "data": {
    "conversationId": "conv-uuid",
    "customerEmail": "john@example.com",
    "customerName": "John Doe",
    "customerPhone": "+639171234567",
    "customFields": {
      "company": "Acme Inc",
      "source": "website"
    }
  }
}

Use cases:

Add lead to CRM (HubSpot, Salesforce)
Send welcome email
Notify sales team via Slack
Add to Google Sheets

message.sent#

Trigger: AI agent sends a message to the user.

Payload:

json

{
  "event": "message.sent",
  "agent_id": "agent-uuid",
  "timestamp": "2026-03-15T10:31:15Z",
  "data": {
    "conversationId": "conv-uuid",
    "messageId": "msg-uuid",
    "content": "Our business hours are 9am-5pm Mon-Fri.",
    "timestamp": "2026-03-15T10:31:15Z",
    "metadata": {
      "sources": ["source-123", "source-456"]
    }
  }
}

Use cases:

Log agent responses for analytics
Track AI performance metrics
Quality assurance monitoring

message.received#

Trigger: User sends a message to the agent.

Payload:

json

{
  "event": "message.received",
  "agent_id": "agent-uuid",
  "timestamp": "2026-03-15T10:31:00Z",
  "data": {
    "conversationId": "conv-uuid",
    "messageId": "msg-uuid",
    "content": "What are your business hours?",
    "timestamp": "2026-03-15T10:31:00Z",
    "userInfo": {
      "email": "john@example.com",
      "name": "John Doe"
    }
  }
}

Use cases:

Track user intent and common queries
Build FAQ from frequently asked questions
Trigger escalation for specific keywords
Customer engagement analytics

conversation.started#

Trigger: A new chat conversation is initiated.

Payload:

json

{
  "event": "conversation.started",
  "agent_id": "agent-uuid",
  "timestamp": "2026-03-15T10:30:00Z",
  "data": {
    "conversationId": "conv-uuid",
    "source": "website",
    "timestamp": "2026-03-15T10:30:00Z",
    "userInfo": {
      "email": "john@example.com",
      "name": "John Doe"
    }
  }
}

Use cases:

Track conversation volume
Identify traffic sources
Real-time visitor monitoring
Trigger proactive outreach

conversation.ended#

Trigger: A chat conversation is closed or ended.

Payload:

json

{
  "event": "conversation.ended",
  "agent_id": "agent-uuid",
  "timestamp": "2026-03-15T10:35:00Z",
  "data": {
    "conversationId": "conv-uuid",
    "duration": 180,
    "messageCount": 12,
    "resolved": true,
    "timestamp": "2026-03-15T10:35:00Z",
    "satisfaction": {
      "rating": 5,
      "feedback": "Very helpful!"
    }
  }
}

Use cases:

Calculate average conversation duration
Track resolution rates
Collect satisfaction metrics
Trigger follow-up surveys

tool.executed#

Trigger: An AI action or tool call completes successfully.

Payload:

json

{
  "event": "tool.executed",
  "agent_id": "agent-uuid",
  "timestamp": "2026-03-15T10:32:00Z",
  "data": {
    "conversationId": "conv-uuid",
    "toolName": "SendFile",
    "toolId": "tool-uuid",
    "result": {
      "success": true,
      "fileUrl": "https://storage.alonchat.com/files/xyz.pdf",
      "fileName": "product-catalog.pdf"
    },
    "executionTime": 1250
  }
}

Use cases:

Track tool usage analytics
Monitor integration health
Audit automated actions
Performance monitoring

tool.failed#

Trigger: An AI action or tool call fails.

Payload:

json

{
  "event": "tool.failed",
  "agent_id": "agent-uuid",
  "timestamp": "2026-03-15T10:32:30Z",
  "data": {
    "conversationId": "conv-uuid",
    "toolName": "CreateCalendarEvent",
    "toolId": "tool-uuid",
    "error": {
      "code": "CALENDAR_FULL",
      "message": "No available slots for requested time"
    }
  }
}

Use cases:

Alert on integration failures
Debug tool issues
Automatic retry triggers
Error monitoring dashboards

integration.connected#

Trigger: A platform integration is connected to the agent (e.g., Facebook, Instagram, Telegram).

Payload:

json

{
  "event": "integration.connected",
  "agent_id": "agent-uuid",
  "timestamp": "2026-03-15T14:00:00Z",
  "data": {
    "platform": "facebook",
    "connectionId": "conn-uuid",
    "pageName": "My Business Page"
  }
}

Use cases:

Track which platforms are active
Trigger onboarding flows
Update internal dashboards

integration.disconnected#

Trigger: A platform integration is disconnected from the agent.

Payload:

json

{
  "event": "integration.disconnected",
  "agent_id": "agent-uuid",
  "timestamp": "2026-03-15T14:30:00Z",
  "data": {
    "platform": "facebook",
    "connectionId": "conn-uuid",
    "reason": "user_disconnected"
  }
}

Use cases:

Alert ops team to connectivity issues
Trigger re-connection flows
Audit integration changes

agent.enabled#

Trigger: An agent is activated and starts responding to messages.

Payload:

json

{
  "event": "agent.enabled",
  "agent_id": "agent-uuid",
  "timestamp": "2026-03-15T09:00:00Z",
  "data": {
    "agentId": "agent-uuid",
    "enabledBy": "user-uuid"
  }
}

agent.disabled#

Trigger: An agent is deactivated and stops responding to messages.

Payload:

json

{
  "event": "agent.disabled",
  "agent_id": "agent-uuid",
  "timestamp": "2026-03-15T18:00:00Z",
  "data": {
    "agentId": "agent-uuid",
    "disabledBy": "user-uuid"
  }
}

agent.trained#

Trigger: Agent training completes successfully.

Payload:

json

{
  "event": "agent.trained",
  "agent_id": "agent-uuid",
  "timestamp": "2026-03-15T11:00:00Z",
  "data": {
    "agentId": "agent-uuid",
    "sourcesCount": 15,
    "chunksCount": 342,
    "duration": 180
  }
}

Use cases:

Notify team when agent knowledge is updated
Track training frequency
Monitor knowledge base growth
Trigger deployment automation

agent.training_failed#

Trigger: Agent training fails.

Payload:

json

{
  "event": "agent.training_failed",
  "agent_id": "agent-uuid",
  "timestamp": "2026-03-15T11:05:00Z",
  "data": {
    "agentId": "agent-uuid",
    "error": {
      "code": "PROCESSING_TIMEOUT",
      "message": "Source processing timed out after 5 minutes"
    },
    "failedSourceId": "source-123"
  }
}

Use cases:

Alert on training failures
Automatic retry logic
Debug source processing issues
Ops monitoring

Payload Structure#

All webhook payloads follow this standard format:

json

{
  "event": "string",
  "agent_id": "string (UUID)",
  "timestamp": "string (ISO 8601)",
  "data": {}
}

Common Fields#

Field	Type	Description
`event`	string	Event identifier (e.g., `leads.submit`)
`agent_id`	UUID	The agent that triggered the event
`timestamp`	ISO 8601	When the event occurred (UTC)
`data`	object	Event-specific payload (varies by event type)

Timestamp Format#

All timestamps use ISO 8601 format with UTC timezone:

Code

2026-03-15T10:30:00Z

Parsing examples:

JavaScript:

javascript

const date = new Date(event.timestamp);

Python:

python

from datetime import datetime
dt = datetime.fromisoformat(event['timestamp'].replace('Z', '+00:00'))

PHP:

php

$date = new DateTime($event['timestamp']);

Event Filtering#

When creating a webhook, choose which events to receive:

From the dashboard:

Go to Settings > Webhooks
Click Add Webhook
Check the events you want

Via the API:

json

{
  "name": "Lead Notifications",
  "endpoint_url": "https://your-server.com/webhooks/alonchat",
  "events": [
    "leads.submit",
    "conversation.ended",
    "agent.trained"
  ]
}

Subscribe only to events you need to reduce webhook traffic and processing overhead.

Event Delivery#

At-Least-Once Delivery#

AlonChat uses at-least-once delivery. Events are guaranteed to be delivered at least once but may be delivered multiple times during retries. Use the x-alonchat-delivery-id header to deduplicate.

javascript

const express = require('express');
const app = express();

const processedDeliveries = new Set();

app.post('/webhooks/alonchat', (req, res) => {
  const deliveryId = req.headers['x-alonchat-delivery-id'];

  if (processedDeliveries.has(deliveryId)) {
    return res.status(200).json({ success: true, duplicate: true });
  }

  // Process event...
  processedDeliveries.add(deliveryId);

  res.status(200).json({ success: true });
});

For production use, store delivery IDs in a database or Redis instead of an in-memory Set.

Delivery Order#

Events are delivered roughly in chronological order, but strict ordering is not guaranteed. Use the timestamp field to determine actual event order when it matters.

Testing Events#

Test Button#

Use the Test button in the dashboard to send a sample payload to your endpoint:

Go to Settings > Webhooks
Click the menu on your webhook > Test
Select an event type
Click Send Test

Test events include a "test": true field so you can distinguish them from real events.

Manual Testing#

Use curl to simulate a webhook delivery:

bash

curl -X POST https://your-endpoint.com/webhooks/alonchat \
  -H "Content-Type: application/json" \
  -H "x-alonchat-signature: sha256=test-signature" \
  -H "x-alonchat-delivery-id: test-delivery-001" \
  -d '{
    "event": "leads.submit",
    "agent_id": "agent-uuid",
    "timestamp": "2026-03-15T10:30:00Z",
    "data": {
      "conversationId": "test-conv",
      "customerEmail": "test@example.com",
      "customerName": "Test User"
    }
  }'

Next Steps#

Webhook Security — HMAC-SHA256 signature verification
Webhook Examples — Real-world integration recipes
Webhooks Overview — Setup and configuration