SMS Webhooks

SMS Webhooks

SMS webhooks POST an event to your server whenever a message is sent, delivered, fails or arrives. 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 webhook. It can be set from the portal in under a minute.

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 SMS webhook, paste your Webhook URL.
5. Click Save.

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 have your endpoint live before you save. To remove the webhook later, clear the field and save again.

The rest of this article covers doing the same thing through the API, which is what you want if you are provisioning accounts 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. Whenever an SMS is sent, delivered, failed, or received inbound, Zonitel sends a POST request to your webhook URL.

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

Important: Requests use Bearer Authentication. Include your access token in the Authorization header.

Register a Webhook

Endpoint:

Request Body (JSON):

Notes:

• URL must be HTTPS and publicly reachable.

• Your server must respond within 5 seconds with HTTP 200 OK.

Example Success Response:

Retrieve Registered Webhook

Endpoint:

Example Response:

Remove the registered SMS webhook

Use DELETE on the same endpoint to stop sending SMS events to your receiver. A successful removal returns HTTP 204.

curl --request DELETE \
  --url https://api.zonitel.com/api/v3/integrations/sms/webhooks \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'X-Client-Id: YOUR_CLIENT_ID'

Webhook Notifications

Inbound SMS Notification

Outbound SMS Status Notification

Common Error Responses

• 401 Unauthorized

• 403 Forbidden

• 400 Bad Request

• 500 Internal Server Error

Best Practices

• Always use HTTPS for webhook URLs.

• Respond with HTTP 200 OK within 5 seconds.

• Keep your Bearer token secure; never share it publicly.

• Test webhook endpoints regularly to ensure reliable delivery.

Going further

Receiving events is one half of a messaging integration. Sending SMS and MMS, looking up a message, checking remaining capacity and scheduling bulk campaigns are covered in Send and Receive SMS with the API.

Need help?

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