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 has the following basic structure:

{
  "account_id": "account id",
  "conversation_id": "conversation id",
  "agent": "agent name",
  "event": "event name",
  "conversation_data": {
    "caller": "calling number",
    "callee": "called number",
    ...
  }
}

Webhooks triggered by user and llm events have an additional content field that contains user utterance / LLM response.

Webhooks triggered by the finish event have an additional transcript field that contains complete conversation transcript.

Webhooks triggered by events received from Live Hub have an additional value field if such was provided in AudioCodes Bot API.

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