Incoming Call Webhooks

Incoming Call Webhooks

Call webhooks POST an event to your server when a call starts, ends or changes status. This guide shows you the quick way to register one from the Private Integrations screen, the HTTP 200 rule that decides whether it saves, and the API method for doing it in code.

The simple way: set it in the portal

You do not need to call the API to register a call webhook. It can be set from the portal directly.

1. Log in to your Zonitel Office Portal.
2. In the left sidebar, expand Settings and click Private Integrations.
3. Open the Webhooks tab.
4. Under Calls webhook, paste your Webhook URL.
5. Click Save.

Zonitel posts an event when a call starts, ends or changes status. The URL has to be valid and answer with HTTP 200 to be saved — if it does not respond correctly it is not stored, so bring your endpoint up first. To remove it later, clear the field and save again.

The rest of this article covers the API method, for setting webhooks programmatically.

Advanced: method and receiver authentication

1. Open Advanced under the webhook URL and enable Use a custom method or authentication.
2. Choose the HTTP method and Authentication your receiving service requires. Methods: POST, PUT, PATCH or GET. Authentication: None, Bearer token, API key, Basic (user + password) or Custom header.
3. Complete the fields shown for that choice and save the webhook. The receiving URL must respond with HTTP 200 for the portal to accept it.

POST with no authentication is the default. GET has no request body; the event travels as query parameters. For API key, select where to send it and enter the header or parameter name required by your receiver.

The optional receiver credentials belong to the service receiving the webhook. They are separate from the Zonitel API token and X-Client-Id used when your software calls our API. Only provide credentials intended for that receiver.

The API registration example below configures the URL. Use the portal for the Advanced options shown here.

How It Works

1. Register a webhook URL in your account.

2. Each incoming call to your client phone numbers triggers a POST request to the configured URL.

3. Your server must respond with HTTP 200 OK within 5 seconds to confirm receipt.

Important: The webhook URL must be HTTPS and publicly accessible from the internet.

Register a Webhook URL

Endpoint:

Request Body (JSON):

Notes:

• URL must be HTTPS and reachable from the public internet.

• Must respond with HTTP 200 OK within 5 seconds.

Success Response (200 OK):

Retrieve Registered Webhook

Endpoint:

Example Response (200 OK):

Webhook Payload Example

When an incoming call is received, your webhook endpoint will receive a POST request with a JSON payload like this:

Payload Fields:

• caller_id_name: The name of the caller (if available).

• caller_id_number: The phone number of the caller.

• destination_number: The client phone number receiving the call.

Common Error Responses

• 401 Unauthorized

• 403 Forbidden

• 404 Not Found

• 500 Internal Server Error

Best Practices

• Always use HTTPS for your webhook URLs.

• Respond with HTTP 200 OK within 5 seconds to acknowledge the call event.

• Keep your Bearer token secure.

• Ensure your webhook endpoint can handle multiple concurrent calls.

Remove a Registered Webhook

Send DELETE to the same address to stop receiving events. Clearing the Calls field on the Webhooks tab of Settings > Private Integrations does the same thing.

DELETE https://api.zonitel.com/api/v3/integrations/calls/webhooks

Going further

Registering the webhook is one half of a call integration. Pulling call history, downloading recordings and transcriptions, and placing calls from your own app are covered in Sync Your Calls with the API.

Need help?

Call/Text/WhatsApp: (833) 966-4835
Email: info@zonitel.com