events

Webhook Events#

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

Event Types#

1. leads.submit#

Trigger: User submits contact form

Payload:

json

{
  "eventType": "leads.submit",
  "chatbotId": "agent-uuid",
  "payload": {
    "conversationId": "conv-uuid",
    "customerEmail": "john@example.com",
    "customerName": "John Doe",
    "customerPhone": "+639171234567",
    "customFields": {
      "company": "Acme Inc",
      "source": "website"
    }
  },
  "timestamp": "2025-11-26T10:30:00Z"
}

Use cases:

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

Example integration:

javascript

if (event.eventType === 'leads.submit') {
  await hubspot.contacts.create({
    email: event.payload.customerEmail,
    firstname: event.payload.customerName.split(' ')[0],
    phone: event.payload.customerPhone
  });
}

2. message.sent#

Trigger: Agent sends message to user

Payload:

json

{
  "eventType": "message.sent",
  "chatbotId": "agent-uuid",
  "payload": {
    "conversationId": "conv-uuid",
    "messageId": "msg-uuid",
    "content": "Our business hours are 9am-5pm Mon-Fri.",
    "timestamp": "2025-11-26T10:31:15Z",
    "metadata": {
      "model": "gpt-4",
      "sources": ["source-123", "source-456"]
    }
  },
  "timestamp": "2025-11-26T10:31:15Z"
}

Use cases:

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

3. message.received#

Trigger: User sends message to agent

Payload:

json

{
  "eventType": "message.received",
  "chatbotId": "agent-uuid",
  "payload": {
    "conversationId": "conv-uuid",
    "messageId": "msg-uuid",
    "content": "What are your business hours?",
    "timestamp": "2025-11-26T10:31:00Z",
    "userInfo": {
      "email": "john@example.com",
      "name": "John Doe"
    }
  },
  "timestamp": "2025-11-26T10:31:00Z"
}

Use cases:

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

4. conversation.started#

Trigger: New chat conversation initiated

Payload:

json

{
  "eventType": "conversation.started",
  "chatbotId": "agent-uuid",
  "payload": {
    "conversationId": "conv-uuid",
    "source": "website",
    "timestamp": "2025-11-26T10:30:00Z",
    "userInfo": {
      "email": "john@example.com",
      "name": "John Doe",
      "ip": "203.123.45.67",
      "userAgent": "Mozilla/5.0..."
    }
  },
  "timestamp": "2025-11-26T10:30:00Z"
}

Use cases:

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

5. conversation.ended#

Trigger: Chat conversation closed or ended

Payload:

json

{
  "eventType": "conversation.ended",
  "chatbotId": "agent-uuid",
  "payload": {
    "conversationId": "conv-uuid",
    "duration": 180,
    "messageCount": 12,
    "resolved": true,
    "timestamp": "2025-11-26T10:35:00Z",
    "satisfaction": {
      "rating": 5,
      "feedback": "Very helpful!"
    }
  },
  "timestamp": "2025-11-26T10:35:00Z"
}

Use cases:

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

6. tool.executed#

Trigger: Tool/function call executed successfully

Payload:

json

{
  "eventType": "tool.executed",
  "chatbotId": "agent-uuid",
  "payload": {
    "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,
    "timestamp": "2025-11-26T10:32:00Z"
  },
  "timestamp": "2025-11-26T10:32:00Z"
}

Use cases:

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

7. tool.failed#

Trigger: Tool/function call failed

Payload:

json

{
  "eventType": "tool.failed",
  "chatbotId": "agent-uuid",
  "payload": {
    "conversationId": "conv-uuid",
    "toolName": "CreateCalendarEvent",
    "toolId": "tool-uuid",
    "error": {
      "code": "CALENDAR_FULL",
      "message": "No available slots for requested time"
    },
    "timestamp": "2025-11-26T10:32:30Z"
  },
  "timestamp": "2025-11-26T10:32:30Z"
}

Use cases:

Alert on integration failures
Debugging tool issues
Automatic retry triggers
Error monitoring

8. agent.trained#

Trigger: Agent training completes successfully

Payload:

json

{
  "eventType": "agent.trained",
  "chatbotId": "agent-uuid",
  "payload": {
    "agentId": "agent-uuid",
    "sourcesCount": 15,
    "chunksCount": 342,
    "duration": 180,
    "timestamp": "2025-11-26T11:00:00Z",
    "stats": {
      "docsChunks": 250,
      "examplesChunks": 50,
      "conversationChunks": 42
    }
  },
  "timestamp": "2025-11-26T11:00:00Z"
}

Use cases:

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

9. agent.training_failed#

Trigger: Agent training fails

Payload:

json

{
  "eventType": "agent.training_failed",
  "chatbotId": "agent-uuid",
  "payload": {
    "agentId": "agent-uuid",
    "error": {
      "code": "EMBEDDING_TIMEOUT",
      "message": "Embedding generation timed out after 5 minutes"
    },
    "failedSourceId": "source-123",
    "timestamp": "2025-11-26T11:05:00Z"
  },
  "timestamp": "2025-11-26T11:05:00Z"
}

Use cases:

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

Payload Structure#

All webhook payloads follow this standard format:

json

{
  "eventType": "string",
  "chatbotId": "string (UUID)",
  "payload": {
    // Event-specific data
  },
  "timestamp": "string (ISO 8601)"
}

Common Fields#

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

Timestamp Format#

All timestamps use ISO 8601 format with UTC timezone:

Code

2025-11-26T10:30:00Z

Parsing examples:

JavaScript:

javascript

const date = new Date(event.timestamp);
console.log(date.toLocaleString());

Python:

python

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

PHP:

php

$date = new DateTime($event['timestamp']);
echo $date->format('Y-m-d H:i:s');

Event Filtering#

Configure which events to receive when creating a webhook:

UI:

Go to Agent Settings → Webhooks
Click "Add Webhook"
Select events:
- ✅ leads.submit
- ✅ message.sent
- ✅ conversation.ended

API:

json

{
  "name": "HubSpot Integration",
  "endpoint_url": "https://api.hubspot.com/webhooks/alonchat",
  "events": [
    "leads.submit",
    "message.sent",
    "conversation.ended"
  ]
}

Best practice: Only subscribe to events you need to reduce webhook traffic.

Event Delivery#

Delivery Guarantee#

AlonChat uses at-least-once delivery:

Events are delivered at least once
May be delivered multiple times (on retries)
Implement idempotency to handle duplicates

Idempotency example:

javascript

const processedEvents = new Set();

app.post('/webhooks/alonchat', async (req, res) => {
  const eventId = req.body.payload.messageId || req.body.timestamp;

  // Check if already processed
  if (processedEvents.has(eventId)) {
    return res.status(200).json({ success: true, duplicate: true });
  }

  // Process event
  await handleEvent(req.body);

  // Mark as processed
  processedEvents.add(eventId);

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

Delivery Order#

Events are delivered roughly in chronological order, but:

Not guaranteed to be strictly ordered
Multiple webhooks for the same agent are independent
Handle out-of-order events gracefully

Example scenario:

Code

message.received (10:30:00)  ← Delivered first
message.sent (10:30:05)      ← Delivered second
message.sent (10:30:03)      ← May arrive out of order!

Solution: Use timestamp field to determine actual order.

Rate Limits#

AlonChat webhook delivery:

Global limit: 10 webhooks/second across all events
Per-endpoint limit: 5 concurrent deliveries
Timeout: 10 seconds per delivery attempt

Exceeding limits:

Events are queued (not dropped)
Delivery may be delayed
Check webhook logs for backlog

Testing Events#

Test Button#

Use the "Test" button in UI to send a test payload:

Go to Agent Settings → Webhooks
Click ⋮ → Test
Select event type
Click "Send Test"

Test payload example:

json

{
  "eventType": "leads.submit",
  "chatbotId": "agent-uuid",
  "payload": {
    "conversationId": "test-conv-uuid",
    "customerEmail": "test@example.com",
    "customerName": "Test User",
    "customerPhone": "+639171234567"
  },
  "timestamp": "2025-11-26T10:30:00Z",
  "test": true
}

Note: Test events include "test": true field.

Manual Testing#

Use curl to simulate webhook delivery:

bash

curl -X POST https://your-endpoint.com/webhooks/alonchat \
  -H "Content-Type: application/json" \
  -H "x-alonchat-signature: test-signature" \
  -d '{
    "eventType": "leads.submit",
    "chatbotId": "agent-uuid",
    "payload": {
      "conversationId": "test-conv",
      "customerEmail": "test@example.com",
      "customerName": "Test User"
    },
    "timestamp": "2025-11-26T10:30:00Z"
  }'

Next Steps#

Webhook Security - HMAC signature verification
Webhook Examples - Real-world integration examples
API Reference - Full API documentation