---
title: "Webhooks overview"
slug: "webhooks-overview"
updated: 2024-10-25T11:06:22Z
published: 2024-10-25T11:06:22Z
canonical: "docs.voiso.com/webhooks-overview"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voiso.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks overview

## Introduction

Webhooks facilitate real-time communication between websites or applications by allowing one application to send HTTP requests, including payload data, to another application when a predefined event or trigger occurs.

With the Voiso **Webhooks** feature, developers can subscribe to call events, offering numerous advantages for custom integrations and automated tasks:

- **Real-time updates**: Receive instant notifications or data updates when specific call events occur.
- **Simplified integration**: Transmit data between applications seamlessly without continuous polling.
- **Efficient resource usage**: Data is only sent when an event occurs, reducing unnecessary network traffic and server load.
- **Automation**: Streamline workflows and enhance overall efficiency in application development and management.

### The Webhooks page

Add and manage your webhooks using the **Webhooks** page. For more information, refer to [Webhooks](https://docs.voiso.com/docs/webhooks) in the Voiso Documentation Portal.

### Webhook response

When coding your response to the webhook, note that Voiso expects an `HTTP 200` status code to indicate a successful operation. If no response is received, Voiso assumes that the request timed out or an error occurred.

### Supported events

The **Webhooks** feature supports the following call events:

| Event | Description | Webhook |
| --- | --- | --- |
| outbound.call.answered | A contact answers an outbound call. | Outbound calls |
| outbound.call.hangup | An outbound call ends. | Outbound calls |
| outbound.call.ended | An outbound call is completed. | Outbound calls |
| inbound.call.answered | An agent answers an inbound call. | Inbound calls |
| inbound.call.hangup | An inbound call ends. | Inbound calls |
| inbound.call.ended | An inbound call is completed. | Inbound calls |
| dialer.call.answered | An agent is connected to a Dialer call answered by a contact. | Outbound dialer campaigns |
| dialer.call.hangup | A Dialer call ends. | Outbound Dialer campaigns |
| dialer.call.ended | A Dialer call is completed. | Outbound Dialer campaigns |
| message.received | An agent receives a new reply in an ongoing conversation. | Digital interactions |
| conversation.ended | A digital conversation is archived (ends), and an agent assigns a wrap-up code. | Digital interactions |

## Voiso webhook structure

Voiso webhooks employ the POST method with the HTTP request protocol when sending data. Requests are structured as follows:

| Parameter | Description | Data type |
| --- | --- | --- |
| name | The name of the webhook. | string |
| event | One of the supported Voiso contact center events. Refer to [Supported events](/v1-api/apidocs/webhooks-overview#supported-events). | string |
| object | The name of the contact center object associated with the webhook data. Objects include `call`, `message`, and `conversation` | string |
| timestamp | The timestamp indicates when the event triggering the webhook occurred. | string |
| secret | Each webhook should have a unique contact center key, secret key, or user-defined token. The external system uses this key to validate the authenticity of the webhook. | string |
| contact_center_id | The UUIS of your contact center. | string |
| data | The payload data contained within the webhook. The structure and content of the payload vary depending on the specific event and object involved. It can be a simple or nested structure, accommodating different scenarios. Refer to individual webhook descriptions for payload details. | Simple or nested structure |

### Common call event objects

The webhooks for outbound, inbound, and dialer events use one or more of the following common objects:

- Call object
- Duration object
- Wrap-up code object
- Campaign object

#### Call object

| Parameter | Description | Data type | Notes |
| --- | --- | --- | --- |
| id | UUID of the call | string |  |
| type | The type of call. | string | Valid values are: `outbound`, `click to call`, `queue callback`, `scheduled callback`,`inbound`, and `dialer`. |
| start_time | The start time of the call. | string | A timestamp in ISO 8601 format (UTC time zone). |
| end_time | The end time of the call. | string | A timestamp in ISO 8601 format (UTC time zone). |
| agent_start_time | The timestamp when the agent was connected. | string | A timestamp in ISO 8601 format (UTC time zone). |
| duration | Details of the duration of the call. | structure | Refer to the Duration object table. |
| disposition | A disposition code to specify whether the interaction was successfully completed, and if not, why not. | string | Refer to [Disposition codes](https://docs.voiso.com/docs/disposition-codes). |
| queue | The name of the inbound queue. | string | For inbound calls. |
| end_reason | And end reason code to specify why the interaction was terminated. | string | Refer to [End reasons](https://docs.voiso.com/docs/end-reasons). |
| script | The name of the inbound flow script. | string |  |
| flow | The name of the inbound flow. | string | Refer to [Flows](https://docs.voiso.com/docs/inbound-flows). |
| calling_number | The ANI of the call. | string | In [E.164 format](https://www.itu.int/rec/T-REC-E.164) without the preceding '+'. For example: `447414992548` |
| called_number | The DNIS of the call. | string | In [E.164 format](https://www.itu.int/rec/T-REC-E.164) without the preceding '+'. For example: `447414992548` |
| wrapup_code | The call outcome specified by the agent. | structure | Refer to the Wrap-up code object table. For information about wrap-up codes, refer to [Wrap-up codes](https://docs.voiso.com/docs/administration-wrap-up-codes). |
| notes | Call notes added by the agent. | string | Up to 280 characters. Refer to [Call notes](https://docs.voiso.com/docs/call-notes) |
| ext_user_id | The external CRM ID for the contact. | string | The `account_id` received from the [Start call](/v1-api/apidocs/start-call) API. |
| cdr_url | The URL of the call recording. | string |  |
| campaign | Information about the Dialer campaign associated with the call. | structure | Refer to the Campaign object table. |

#### Duration object

The Duration object is a sub-object of the Call object.

| Parameter | Description | Data type | Notes |
| --- | --- | --- | --- |
| total | The total duration of the call in seconds. | number |  |
| queue_time | The duration, in seconds, that the inbound call remained in the queue. | number |  |
| dialing_time | The duration, in seconds, from when a call was initiated until the call was successfully connected. | number |  |
| dialer_waiting | The duration, in seconds, that the Dialer was in the waiting state. | number |  |
| talk_time | The duration, in seconds, of the interaction Talk Time. | number |  |
| hold_time | The duration, in seconds, that the interaction was in the Hold state. | number |  |
| postcall_time | The duration, in seconds, that the call was in the Postcall state. | number |  |

#### Wrap-up code object

The Wrap-up code object is a sub-object of the Call object. Refer to [Wrap-up codes](https://docs.voiso.com/docs/administration-wrap-up-codes).

| Parameter | Description | Data type | Notes |
| --- | --- | --- | --- |
| code | The wrap-up code value. | string |  |
| description | The text description of the wrap-up code. | string |  |

#### Agent object

The Agent object is a sub-object of the Call object. Refer to [Users](https://docs.voiso.com/docs/users-users).

| Parameter | Description | Data type | Notes |
| --- | --- | --- | --- |
| id | The ID of the agent who handled the interaction. | number |  |
| name | The name of the agent who handled the interaction. | string |  |
| email | The sign-in email address of the agent who handled the interaction. | string |  |
| extension | The contact center extension of the agent who handled the interaction. | string |  |

#### Campaign object

The Campaign object is a sub-object of the Call object. Refer to [Campaigns page](https://docs.voiso.com/docs/outbound-dialer-campaigns-view).

| Parameter | Description | Data type | Notes |
| --- | --- | --- | --- |
| id | The ID of the Dialer campaign. | number |  |
| name | The name of the Dialer campaign. | string |  |
| is_live | Whether or not the Dialer campaign is of type Live. | string | Supported values are `True` or `False`. |

### Common digital interaction event objects

The webhooks for digital events use one or more of the following common objects:

- Conversation object
- SLA object
- Agent object
- Message object
- Content Data objects
- Contact object
- Channel object

#### Conversation object

| Parameter | Description | Data type | Notes |
| --- | --- | --- | --- |
| id | The UUID of the conversation. | string |  |
| wrapup_code | The interaction outcome specified by the agent. | structure | For information about wrap-up codes, refer to [Wrap-up codes](https://docs.voiso.com/docs/administration-wrap-up-codes). |
| queue | The name of the inbound queue. | string | For inbound interactions. |
| disposition | A disposition code to specify whether the interaction was successfully completed, and if not, why not. | string | The following values are supported: `waiting`, `active`, `archived`, and `initiated`. Refer to [Disposition codes](https://docs.voiso.com/docs/disposition-codes). |
| source | The source of the interaction. | string | The following values are supported: `user` and `business`. |
| cpc | The cost of the interaction. | number | In US dollars. |
| sla | Service level agreement values. | object | Refer to the SLA object table. |

#### SLA object

The SLA object is a sub-object of the Conversation object.

| Parameter | Description | Data type | Notes |
| --- | --- | --- | --- |
| time_to_first_response | The time in seconds to the first agent's response to the interaction. | number |  |
| time_to_resolution | The time in seconds to the first resolution/archive of the interaction. | number |  |
| time_to_reply | The average waiting time in seconds for the agent's replies | number |  |

#### Agent object

| Parameter | Description | Data type | Notes |
| --- | --- | --- | --- |
| id | The ID of the agent who handled the interaction. | number |  |
| name | The name of the agent who handled the interaction. | string |  |
| email | The sign-in email address of the agent who handled the interaction. | string |  |
| extension | The contact center extension of the agent who handled the interaction. | string |  |

#### Message object

| Parameter | Description | Data type | Notes |
| --- | --- | --- | --- |
| id | The UUID of the message. | string |  |
| conversation_id | The UUID of the associated conversation. | string | Refer to the Conversation object table. |
| reference_id | The Reference Message ID. | string |  |
| content_type | The content type of the message. | string enum | Supported values are: `text`, `image`, `document`, `video`, `voice`, and `audio`. Refer to the Content Data objects table. |

#### Content Data objects

The Content Data objects are sub-objects of the Message object.

The following table describes the content data for text messages:

| Parameter | Description | Data type | Notes |
| --- | --- | --- | --- |
| text | The body of the message sent by the contact. | string |  |

The following table describes the content data for media messages (attachments):

| Parameter | Description | Data type | Notes |
| --- | --- | --- | --- |
| filename | The name of the attached file. | string |  |
| size | The size in bytes of the attached file. | number |  |
| caption | Text description of the file. | string | Can be empty. |
| media_url | The URL of the attached file. | string |  |

#### Contact object

| Parameter | Description | Data type | Notes |
| --- | --- | --- | --- |
| id | The ID number of the channel in your contact center. | number |  |
| username | The username or name of the contact. | string |  |
| channel_identifier | The identifier of the channel. | string | This can be a username or a UUID. |

#### Channel object

| Parameter | Description | Data type | Notes |
| --- | --- | --- | --- |
| id | The UUID of the channel in your contact center. | string |  |
| type | The digital channel type. | string | Supported values include: `whatsapp`, `chat`, `facebook`, `instagram`, `telegram`, and `viber`. |
| name | The name associated with the channel in your contact center. | string |  |

## Related

- [Outbound call events](/outbound-call-events.md)
- [Inbound call events](/inbound-call-events.md)
- [Dialer call events](/dialer-call-events.md)
- [Digital interaction webhooks](/digital-interaction-webhooks.md)
- [Call Notify](/call-notify.md)
- [Call Outcome Logging](/call-outcome-logging.md)