​

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:

​

Request Format

​

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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"
  }
}

​

Webhook Test Event

Type: webhook_test

Payload fields:

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

Sample:

{
  "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:

{
  "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.