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.

Event Types & Categories

Below are all possible event types you can subscribe to:

Event Type	Category	Description
`agent_created`	Agent Events	Agent was created
`agent_updated`	Agent Events	Agent was updated
`agent_deleted`	Agent Events	Agent was deleted
`message_received`	Message Events	Message received on any channel
`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
`lead_captured`	Lead Events	Lead was captured by an agent
`form_submitted`	Form Events	Form was submitted
`chat_delegated`	Chat Events	Chat was delegated to a team member
`bug_reported`	Bug Events	Bug or issue was reported
`webhook_test`	Test Event	Used for testing your webhook endpoint

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": "john.doe@example.com",
    "operation": "created",
    "createdAt": 1718035200000,
    "workspaceSecret": "your_workspace_secret"
  }
}

Lead Events

Types: lead_captured 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": "jane.smith@example.com",
    "leadPhone": "+9876543210",
    "channel": "web-chat",
    "operation": "captured",
    "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": "john.doe@example.com",
    "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 30 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.

​Webhook Documentation

​Event Types & Categories

​Request Format

​Event Categories & Payloads

​Agent Events

​Message Events

​Organisation Events

​Client Events

​Lead Events

​Bug Events

​Webhook Test Event

​Implementation Guidelines

​Best Practices

​Testing Your Webhook

​Subscribing to Events

Webhook Documentation

Event Types & Categories

Request Format

Event Categories & Payloads

Agent Events

Message Events

Organisation Events

Client Events

Lead Events

Bug Events

Webhook Test Event

Implementation Guidelines

Best Practices

Testing Your Webhook

Subscribing to Events