Skip to content

Webhooks Overview

Webhooks allow your application to receive notifications when important events happen in the call center platform (calls, messages, contacts, lists, etc).

When an event occurs, the system sends an HTTP POST request with a JSON payload to the webhook URL you configured.

How webhooks work

  1. You create a webhook in the UI and select:

    • the target URL
    • the events you want to receive
    • optional contact lists to filter events

  2. When an event happens:

    • the platform builds a JSON payload
    • sends it as a POST request to your webhook URL
    • retries automatically on transient failures

  3. Your server processes the payload and returns any 2xx response to acknowledge delivery.

Webhook URL

Each webhook has a single target URL.

All events selected for that webhook are delivered to the same URL.
You must route and handle different event types by inspecting the event name and the JSON body.

Event types

The platform currently sends the following webhook events:

Contact events

Name Description
Contact Created A new contact was created
Contact Modified An existing contact was updated

Contact list events

Name Description
Contact List Created A contact list became non-empty (created)
Contact List Modified A contact list was updated

Call events

Name Description
Call Ended A call finished
Call Abandoned Caller hung up before being answered
Call Overflowed To Voicemail Call was routed to voicemail
Call Disposition Saved A disposition was saved
Call Disposition Modified A disposition was changed
Call Recording Received All call recordings are available

Messaging events

Name Description
Message Received An inbound message was received
Message Sent An outbound message was sent

Each event has its own documentation file describing the payload format and examples.

Delivery & retries

  • Webhooks are sent using HTTP POST with a JSON body.
  • A request is considered successful if your server returns any 2xx status code.

The system automatically retries failed requests:

  • Up to 3 retries (maximum 4 total attempts)
  • Retries happen only for:
  • connection errors
  • 5xx server responses
  • 4xx responses are not retried
  • Exponential backoff is used: 1s → 2s → 4s

Ordering and duplicates

  • Events for the same call or message are sent in the order they occur.
  • Because of retries, duplicate deliveries are possible.
  • Your webhook endpoint must be idempotent and handle the same event more than once safely.

Required behavior for your endpoint

Your webhook endpoint must:

  • Accept POST requests with a JSON body
  • Respond with a 2xx status code as fast as possible
  • Be able to process:
  • missing fields
  • null values
  • empty arrays
  • duplicate events

Security

At this time: - Requests are not signed - No secret or HMAC header is sent

You should protect your webhook endpoint using: - a private, unguessable URL - IP allow-listing (if available) - or your own validation logic