SMS Webhooks

5 min read
1.8K views

SMS Webhooks

SMS Webhooks allow your application to receive real-time notifications about SMS events, such as delivery status updates or inbound messages. This enables automation, tracking, and instant processing of SMS activity.

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:

 
PUT https://api.zonitel.com/api/v3/integrations/sms/webhooks Content-Type: application/json X-Client-Id: 550e8400-e29b-41d4-a716-446655440000 Authorization: Bearer <YOUR_ACCESS_TOKEN> 

Request Body (JSON):

 
{ "url": "https://yourdomain.com/api/sms-webhook" }

Notes:

  • URL must be HTTPS and publicly reachable.

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

Example Success Response:

 
{ "status": "success", "data": { "url": "https://yourdomain.com/api/sms-webhook" }, "message": "Webhook updated successfully" }

Retrieve Registered Webhook

Endpoint:

 
GET https://api.zonitel.com/api/v3/integrations/sms/webhooks X-Client-Id: 550e8400-e29b-41d4-a716-446655440000 Authorization: Bearer <YOUR_ACCESS_TOKEN>

Example Response:

 
{ "status": "success", "data": { "url": "https://yourdomain.com/api/sms-webhook" }, "message": "Webhook retrieved successfully" }

Webhook Notifications

Inbound SMS Notification

 
{ "status": "received", "data": { "id": "11111111-aaaa-2222-bbbb-333333333333", "segments": 1, "direction": "inbound", "messageText": "Hello, this is a test SMS", "from": "+10000000010", "to": "+10000000020", "medias": [] }, "message": "SMS message received successfully" }

Outbound SMS Status Notification

 
{ "status": "delivered", "data": { "id": "44444444-cccc-5555-dddd-666666666666", "segments": 1, "direction": "outbound", "messageText": "Test outbound SMS with media", "from": "+10000000020", "to": "+10000000030", "medias": [ "https://example.com/media1.jpg" ] }, "message": "SMS message delivered successfully" }

Common Error Responses

  • 401 Unauthorized

 
{ "code": 401, "message": "Authentication required" }

  • 403 Forbidden

 
{ "code": 403, "message": "Access denied" }

  • 400 Bad Request

 
{ "code": 400, "message": "Invalid request parameters" }

  • 500 Internal Server Error

 
{ "code": 500, "message": "An internal server error occurred" }

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.

Was this article helpful?

Yes No

Related Articles

Integrations

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.

5min 1.8K views
Integrations

Private Integrations

Automate SMS, calls, and events using our API. With our integration tools, you can securely connect your account with third-party applications, CRMs, or custom systems to send messages, trigger calls, and handle events automatically.

4min 1.8K views

Still Have Questions?

Our support team is available 24/7 to help you get started

Chat with us on WhatsApp