Incoming Call Webhooks

Incoming Call Webhooks

Incoming Call Webhooks allow your application to receive real-time notifications whenever a call is received on your client phone numbers. This enables you to process, route, log, or handle calls programmatically as they arrive.

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.