Webhook Documentation

Events are sent as HTTP POST requests to your configured endpoint with a structured JSON payload. Each event contains comprehensive information about the action that occurred in your workspace.

Platform Compatibility

Important: Not all events are available for all agent platforms. VoiceFlow (VF) agents support a subset of events compared to Convocore agents.

Platform	Description
Convocore	Convocore agents (built with the Convocore node-based builder)
VF	VoiceFlow agents (imported from VoiceFlow or using VoiceFlow runtime)

Event Types & Categories

Below are all possible event types you can subscribe to:

Event Type	Category	Convocore Support	VF Support	Description
`message_received`	Message Events	✅	✅	Message received on any channel
`chat_delegated`	Chat Events	✅	✅	Chat was delegated to a team member
`bug_reported`	Bug Events	✅	✅	Bug or issue was reported
`agent_deleted`	Agent Events	✅	✅	Agent was deleted
`webhook_test`	Test Event	✅	✅	Used for testing your webhook endpoint
`lead_captured`	Lead Events	✅	❌	Lead was captured by an agent (Convocore only)
`form_submitted`	Form Events	✅	❌	Form was submitted (Convocore only)
`organisation_created`	Organisation Events	✅	✅	Organisation was created
`organisation_updated`	Organisation Events	✅	✅	Organisation was updated
`organisation_deleted`	Organisation Events	✅	✅	Organisation was deleted
`client_created`	Client Events	✅	✅	Client was created
`client_updated`	Client Events	✅	✅	Client was updated
`client_deleted`	Client Events	✅	✅	Client was deleted

Why are some events Convocore-only?Convocore agents use WebSocket-based interactions that support advanced features like:

Automatic lead collection based on conversation analysis
UI Engine forms with dynamic form submissions
Real-time streaming responses

VF agents use REST API-based interactions and rely on VoiceFlow’s native capabilities, which don’t include these features.

Request Format

Property	Value
HTTP Method	`POST`
Content Type	`application/json`

Event Categories & Payloads

Agent Events

Types: agent_created, agent_updated, agent_deleted Payload fields:

agentId (string): The ID of the agent
agentName (string, optional): The name of the agent
agentPlatform (“vg” | “vf”, optional): The platform of the agent
operation (“created” | “updated” | “deleted”): The operation performed
createdAt (number): Timestamp (ms)
workspaceSecret (string): Workspace secret for verification

Sample:

Agent Created Event

{
  "type": "agent_created",
  "payload": {
    "agentId": "agent_123456",
    "agentName": "Customer Support Bot",
    "agentPlatform": "vf",
    "operation": "created",
    "createdAt": 1718035200000,
    "workspaceSecret": "your_workspace_secret"
  }
}

Message Events

Types: message_received Payload fields:

agentId (string): The ID of the agent
agentName (string, optional): The name of the agent
convoId (string): The ID of the conversation
messageContent (string): The content of the message
channel (“whatsapp” | “instagram” | “facebook” | “telegram” | “webchat”): The channel
messageType (string, optional): The type of the message
from (string, optional): The sender
createdAt (number): Timestamp (ms)
workspaceSecret (string): Workspace secret for verification

Sample:

Message Received Event

{
  "type": "message_received",
  "payload": {
    "agentId": "agent_123456",
    "agentName": "Customer Support Bot",
    "convoId": "convo_789012",
    "messageContent": "Hello, I need help with my order",
    "channel": "whatsapp",
    "messageType": "text",
    "from": "+1234567890",
    "createdAt": 1718035200000,
    "workspaceSecret": "your_workspace_secret"
  }
}

Organisation Events

Types: organisation_created, organisation_updated, organisation_deleted Payload fields:

organisationId (string): The ID of the organisation
organisationName (string, optional): The name of the organisation
operation (“created” | “updated” | “deleted”): The operation performed
createdAt (number): Timestamp (ms)
workspaceSecret (string): Workspace secret for verification

Sample:

Organisation Created Event

{
  "type": "organisation_created",
  "payload": {
    "organisationId": "org_345678",
    "organisationName": "Acme Corporation",
    "operation": "created",
    "createdAt": 1718035200000,
    "workspaceSecret": "your_workspace_secret"
  }
}

Client Events

Types: client_created, client_updated, client_deleted Payload fields:

organisationId (string): The ID of the organisation
organisationName (string, optional): The name of the organisation
clientId (string): The ID of the client
clientName (string, optional): The name of the client
clientEmail (string, optional): The email of the client
operation (“created” | “updated” | “deleted”): The operation performed
createdAt (number): Timestamp (ms)
workspaceSecret (string): Workspace secret for verification

Sample:

Client Created Event

{
  "type": "client_created",
  "payload": {
    "organisationId": "org_345678",
    "organisationName": "Acme Corporation",
    "clientId": "client_901234",
    "clientName": "John Doe",
    "clientEmail": "[email protected]",
    "operation": "created",
    "createdAt": 1718035200000,
    "workspaceSecret": "your_workspace_secret"
  }
}

Lead Events

Types: lead_captured

Platform Support: This event is only available for Convocore agents. VoiceFlow (VF) agents do not support automatic lead capture.

Payload fields:

agentId (string): The ID of the agent
agentName (string, optional): The name of the agent
leadName (string, optional): The name of the lead
leadEmail (string, optional): The email of the lead
leadPhone (string, optional): The phone of the lead
channel (see below): The channel where the lead was captured
operation (“captured”): The operation performed
createdAt (number): Timestamp (ms)
workspaceSecret (string): Workspace secret for verification

Possible channel values:

voice, vapi, web-chat, whatsapp, instagram, telegram, discord, gb-chat, messenger, telephony, webchat

Sample:

Lead Captured Event

{
  "type": "lead_captured",
  "payload": {
    "agentId": "agent_123456",
    "agentName": "Sales Bot",
    "leadName": "Jane Smith",
    "leadEmail": "[email protected]",
    "leadPhone": "+9876543210",
    "channel": "web-chat",
    "operation": "captured",
    "createdAt": 1718035200000,
    "workspaceSecret": "your_workspace_secret"
  }
}

Form Events

Types: form_submitted

Platform Support: This event is only available for Convocore agents. VoiceFlow (VF) agents do not support UI Engine forms.

Payload fields:

agentId (string): The ID of the agent
agentName (string, optional): The name of the agent
convoId (string): The ID of the conversation
formType (“ui_engine_form” | “ui_engine_input”): The type of form submitted
formData (object): The submitted form data as key-value pairs
channel (see below): The channel where the form was submitted
createdAt (number): Timestamp (ms)
workspaceSecret (string): Workspace secret for verification

Possible channel values:

voice, vapi, web-chat, whatsapp, instagram, telegram, discord, gb-chat, messenger, telephony, webchat

Sample:

Form Submitted Event

{
  "type": "form_submitted",
  "payload": {
    "agentId": "agent_123456",
    "agentName": "Support Bot",
    "convoId": "convo_789012",
    "formType": "ui_engine_form",
    "formData": {
      "name": "John Doe",
      "email": "[email protected]",
      "message": "I need help with my order"
    },
    "channel": "webchat",
    "createdAt": 1718035200000,
    "workspaceSecret": "your_workspace_secret"
  }
}

Chat Delegation Events

Types: chat_delegated Payload fields:

agentId (string): The ID of the agent
agentName (string, optional): The name of the agent
convoId (string): The ID of the conversation
assignedToUserId (string): The ID of the user the chat was assigned to
assignedToUserName (string, optional): The name of the assigned user
assignedToUserEmail (string, optional): The email of the assigned user
delegatedByUserId (string, optional): The ID of the user who delegated
delegatedByUserName (string, optional): The name of the user who delegated
customerName (string, optional): The name of the customer
customerEmail (string, optional): The email of the customer
customerPhone (string, optional): The phone of the customer
channel (see below): The channel where the delegation occurred
operation (“delegated”): The operation performed
createdAt (number): Timestamp (ms)
workspaceSecret (string): Workspace secret for verification

Possible channel values:

voice, vapi, web-chat, whatsapp, instagram, telegram, discord, gb-chat, messenger, telephony, webchat

Sample:

Chat Delegated Event

{
  "type": "chat_delegated",
  "payload": {
    "agentId": "agent_123456",
    "agentName": "Support Bot",
    "convoId": "convo_789012",
    "assignedToUserId": "user_456789",
    "assignedToUserName": "Support Agent",
    "assignedToUserEmail": "[email protected]",
    "delegatedByUserId": "user_111222",
    "delegatedByUserName": "Manager",
    "customerName": "Jane Doe",
    "customerEmail": "[email protected]",
    "customerPhone": "+1234567890",
    "channel": "webchat",
    "operation": "delegated",
    "createdAt": 1718035200000,
    "workspaceSecret": "your_workspace_secret"
  }
}

Bug Events

Type: bug_reported Payload fields:

agentId (string): The ID of the agent
agentName (string, optional): The name of the agent
convoId (string): The ID of the conversation
bugDescription (string): The description of the bug or issue
imageUrl (string, optional): The CDN URL of the screenshot (automatically uploaded if provided)
reportedByUserId (string, optional): The ID of the user who reported the bug
reportedByUserName (string, optional): The name of the user who reported the bug
reportedByUserEmail (string, optional): The email of the user who reported the bug
channel (see below): The channel where the bug occurred
operation (“reported”): The operation performed
createdAt (number): Timestamp (ms)
workspaceSecret (string): Workspace secret for verification

Possible channel values:

voice, vapi, web-chat, whatsapp, instagram, telegram, discord, gb-chat, messenger, telephony, webchat

Note: When a screenshot is uploaded, it is automatically uploaded to the CDN and only the URL is sent in the webhook payload to keep the payload size minimal. Sample:

Bug Reported Event

{
  "type": "bug_reported",
  "payload": {
    "agentId": "agent_123456",
    "agentName": "Support Bot",
    "convoId": "convo_789012",
    "bugDescription": "The bot is not responding to user inputs correctly",
    "imageUrl": "https://cdn.voiceglow.org/bug-reports/user_123/1234567890.png",
    "reportedByUserId": "user_345678",
    "reportedByUserName": "John Doe",
    "reportedByUserEmail": "[email protected]",
    "channel": "webchat",
    "operation": "reported",
    "createdAt": 1718035200000,
    "workspaceSecret": "your_workspace_secret"
  }
}

Webhook Test Event

Type: webhook_test Payload fields:

message (string): Test message
createdAt (number): Timestamp (ms)
workspaceSecret (string): Workspace secret for verification

Sample:

Webhook Test Event

{
  "type": "webhook_test",
  "payload": {
    "message": "This is a test event",
    "createdAt": 1718035200000,
    "workspaceSecret": "your_workspace_secret"
  }
}

Implementation Guidelines

Response Requirements:
- Return HTTP 200 status for successful receipt
- Response within 60 seconds timeout
- Empty response body is acceptable
Delivery Behavior:
- Events delivered in real-time
- No automatic retry mechanism
- Order of delivery not guaranteed
Data Format:
- Timestamps in milliseconds (Unix epoch)
- UTF-8 encoded JSON payload
- All fields are consistent across events
Security & Performance:
- Use workspace secret for verification
- Ensure endpoint can handle event volume
- Implement proper error handling

Best Practices

Validate the workspace secret on every incoming webhook to ensure authenticity
Implement idempotency handling using the event timestamp and payload data
Use asynchronous processing for webhook handling to avoid timeout issues
Log all incoming webhooks for debugging and monitoring purposes

Testing Your Webhook

You can test your webhook endpoint using the webhook_test event. This event is sent with a simple payload and can be used to verify your endpoint is reachable and correctly configured. Sample:

Webhook Test Event

{
  "type": "webhook_test",
  "payload": {
    "message": "This is a test event",
    "createdAt": 1718035200000,
    "workspaceSecret": "your_workspace_secret"
  }
}

Subscribing to Events

You can subscribe to one or more event types. Only events you are subscribed to will be sent to your endpoint. The workspace secret is included in every payload for verification and security. To update your subscriptions, use the dashboard or API as appropriate.

Get Started

Build Your Agent

Voice

Deploy

Channels & Integrations

Features

Business

Support

Events Webhook

Webhook Documentation

Platform Compatibility

Event Types & Categories

Request Format

Event Categories & Payloads

Agent Events

Message Events

Organisation Events

Client Events

Lead Events

Form Events

Chat Delegation Events

Bug Events

Webhook Test Event

Implementation Guidelines

Best Practices

Testing Your Webhook

Subscribing to Events

Get Started

Build Your Agent

Voice

Deploy

Channels & Integrations

Features

Business

Support

​Webhook Documentation

​Platform Compatibility

​Event Types & Categories

​Request Format

​Event Categories & Payloads

​Agent Events

​Message Events

​Organisation Events

​Client Events

​Lead Events

​Form Events

​Chat Delegation Events

​Bug Events

​Webhook Test Event

​Implementation Guidelines

​Best Practices

​Testing Your Webhook

​Subscribing to Events

Webhook Documentation

Platform Compatibility

Event Types & Categories

Request Format

Event Categories & Payloads

Agent Events

Message Events

Organisation Events

Client Events

Lead Events

Form Events

Chat Delegation Events

Bug Events

Webhook Test Event

Implementation Guidelines

Best Practices

Testing Your Webhook

Subscribing to Events