Webhooks configuration

The webhook configuration allows you to set up HTTP/HTTPS callbacks that are triggered during agent execution. Webhooks can be configured to listen for specific events and send data to external services.

Use webhooks advanced configuration parameter to configure agent webhooks:

Parameter	Type	Description
`webhooks`	list[WebhookModel]	Webhooks to be called during the agent execution.

WebhookModel

Parameter	Type	Default	Description
`events`	list[str]	`[]`	List of events to trigger the webhook. Valid events are `init`, `user`, `llm`, `finish` and any Voice.AI Connect event name.
`url`	str	`null`	Webhook URL, which must start with "http://" or "https://".
`auth`	str	none	Authentication type for the webhook: `none` – No authentication `bearer` – Bearer authentication
`token`	str	`null`	Bearer token for authentication (only applicable when `auth` is `bearer`).
`timeout`	int	`10`	Timeout (in seconds) for the webhook call.
`response`	bool	`false`	Defines whether to wait for the webhook response.
`logs`	bool	`false`	Enables webhook logs (only applicable when `response` is `true`).

Event types

Webhooks can be triggered by the following built-in events:

init - triggered when the agent is initialized
user - triggered on every user utterance
llm - triggered on every LLM response
finish - triggered when the agent completes execution

Additionally, any Live Hub event name (for example, voiceDetected) can be used to trigger webhooks. For more details, see the section Receiving notifications in the Voice AI Connect guide.

Configuration example

{
  "webhooks": [
    {
      "events": [
        "init",
        "finish"
      ],
      "url": "https://api.example.com/webhook",
      "auth": "none",
      "timeout": 30
    }
  ]
}

Webhook request

Webhook request contains the following data:

Event	Parameter	Type	Description
any	`account_id`	str	Account ID
any	`conversation_id`	str	Unique conversation ID
any	`agent`	str	Agent name
any	`event`	str	Event name
any	`conversation_data`	dict	Conversation data
user, llm	`content`	str	User utterance or LLM response
finish	`start_time`	str	Conversation start time
finish	`end_time`	str	Conversation end time
finish	`duration`	int	Conversation duration in seconds
finish	`transcript`	str	Complete conversation transcript
finish	`tokenUsage`	dict	Detailed token usage statistics
finish	`embeddingTokens`	int	Number of embedding tokens (if applicable)
events	`value`	str	Value provided by AudioCodes Bot API for LiveHub events

For example:

{
    "account_id": "b2f48de4-f5e2-3a4d-7fcf-2594a1691d76",
    "conversation_id": "19254074-459e-4cb9-9c39-7c3f23cfac31",
    "agent": "appointment-reminder",
    "event": "finish",
    "conversation_data": {
        "callee": "+14081112222",
        "caller": "+14081113333",
        "type": "call"
    },
    "start_time": "2025-09-11T11:06:37.376Z",
    "end_time": "2025-09-11T11:07:11.721Z",
    "duration": 34,
    "transcript": "LLM   : Hello, this is Dana from \"Tooth or Dare\" dental clinic. May I speak with Jonathan, please?\nUSER  : Yeah, I'm speaking.\nLLM   : Great!...",
    "tokenUsage": {
        {
            "agentName": "appointment-reminder",
            "llmModel": "gpt-4o",
            "inputTokens": 1382,
            "cachedTokens": 0,
            "outputTokens": 94
        }
    }
}

Webhooks are by default sent asynchronously and don't introduce any delay in normal conversation flow. If you want to consume webhook response (see below), you need to set the response property to true in the webhook configuration, for example:

{
  "webhooks": [
    {
      "events": ["user"],
      "url": "https://api.example.com/webhook",
      "response": true
    }
  ]
}

Webhook responses

Webhooks with response property set to true may return the following data:

Event	Parameter	Type	Description
any	`variables`	dict[str, str]	Dictionary of variables that are added / merged to the current agent's variables.
any	`config`	dict[str, str]	Dictionary of advanced configuration parameters that are added / merged to the current agent.
init	`agent`	Str	Name of the agent that starts the conversation.
init	`documents`	list[str]	Names of documents that the agent has access to. May be used to limit access to specific documents based, for example, on the callee number.
user, llm	`content`	str	Modified user utterance / LLM response.
user	`response`	str	Response to the user utterance, instead of using LLM to generate it.
init, user	`tool`	dict[ToolModel]	Calls one of the following pre-defined tools: `pass_question` `send_message` `end_call` `transfer_call`
init	`welcome`	str	Welcome message

ToolModel

Parameter	Type	Description
`name`	str	Tool name
`data`	dict[str, Any]	Tool parameters

Response examples

set variables:
  {"variables": {"sex": "male", "age": 18}}

modify user utterance:
  {"content": "What is the weather in London, UK?"}

respond to user:
  {"response": "I'm not familiar with city Looondn. Please specify a different one."}

call pre-defined tools:
  {
    "tool": {
      "name": "pass_question",
      "data": {"agent": "hogwarts-finance"}
    }
  }
  {
    "tool": {
      "name": "send_message",
      "data": {
        "agent": "doctor-cancel",
        "message": "Cancel appointment for John"
      }
    }
  }
  {
    "tool": {
      "name": "end_call",
      "data": {
        "termination_message": "Have a nice day!"
      }
    }
  }
  {
    "tool": {
      "name": "transfer_call",
      "data": {
        "phone": "+12024561111",
        "transfer_message": "Let me transfer you to human agent"
      }
    }
  }