Delivery Status Callbacks

Zeckta can send real-time delivery status updates to a callback URL that you provide when submitting a message or campaign. Instead of repeatedly polling the Message Status API, your application can receive delivery events automatically as they occur. Callback URLs can be supplied when:

Sending a single SMS
Creating an SMS campaign

When a message reaches a significant delivery milestone, Zeckta performs an HTTP POST request to the configured callback URL.

Supported Delivery Statuses

Status	Description
`SUBMITTED`	Message accepted by Zeckta and queued for delivery.
`SENT`	Message successfully submitted to the upstream carrier.
`DELIVERED`	Message confirmed delivered to the recipient handset.
`FAILED`	Delivery attempt failed.
`UNDELIVERABLE`	Destination number could not be reached.
`EXPIRED`	Message validity period expired before delivery.
`REJECTED`	Message was rejected before delivery processing.

The following internal processing states do not generate callback notifications:

QUEUED
PROCESSING
SCHEDULED
BUFFERED

Event Types

Each callback includes an event type representing the delivery milestone that occurred.

Event Type	Delivery Status
`MESSAGE_SUBMITTED`	`SUBMITTED`
`MESSAGE_SENT`	`SENT`
`MESSAGE_DELIVERED`	`DELIVERED`
`MESSAGE_FAILED`	`FAILED`
`MESSAGE_UNDELIVERABLE`	`UNDELIVERABLE`
`MESSAGE_EXPIRED`	`EXPIRED`
`MESSAGE_REJECTED`	`REJECTED`

Configuring a Callback URL

Single SMS

{
  "src": "ZECKTA",
  "dest": "+233202007745",
  "message": "Hello from Zeckta",
  "callbackUrl": "https://example.com/callbacks/sms"
}

SMS Campaign

{
  "name": "June Promotion",
  "src": "ZECKTA",
  "dests": [
    "+233202007745",
    "+233244111222"
  ],
  "message": "Special offer available now.",
  "callbackUrl": "https://example.com/callbacks/campaigns"
}

Example Callback Payload

{
  "eventId": "4075b658-81d8-4f66-8da4-eb88ac4592b6",
  "eventType": "MESSAGE_DELIVERED",
  "timestamp": "2026-06-09T13:04:57.487133482Z",
  "message": {
    "uuid": "016205e1-6653-47fa-9c8b-e5c46945b81e",
    "src": "ZECKTA",
    "dest": "+233202007745",
    "status": "DELIVERED",
    "segments": 1,
    "units": 1,
    "attempts": 1,
    "cost": 1
  }
}

Payload Fields

Event Metadata

Field	Description
`eventId`	Unique identifier for the callback event.
`eventType`	Delivery event being reported.
`timestamp`	ISO-8601 timestamp when the event occurred.

Message Object

Field	Description
`message.uuid`	Unique identifier of the SMS message.
`message.src`	Sender ID used for the message.
`message.dest`	Recipient phone number.
`message.status`	Current delivery status.
`message.segments`	Number of SMS segments consumed.
`message.units`	Billing units consumed.
`message.attempts`	Number of delivery attempts made.
`message.cost`	Final message cost, if available.

Delivery Lifecycles

Successful Delivery

MESSAGE_SUBMITTED
        ↓
MESSAGE_SENT
        ↓
MESSAGE_DELIVERED

Failed Delivery

MESSAGE_SUBMITTED
        ↓
MESSAGE_FAILED

Expired Message

MESSAGE_SUBMITTED
        ↓
MESSAGE_EXPIRED

Rejected Message

MESSAGE_REJECTED

HTTP Requirements

Your callback endpoint should:

Accept HTTP POST requests
Return a successful 2xx response
Be publicly accessible
Support HTTPS
Process notifications idempotently

Example response:

HTTP/1.1 200 OK

Idempotency

Callback notifications should be treated as idempotent. Although every callback contains a unique eventId, your application should safely handle duplicate deliveries without creating duplicate records or triggering duplicate business actions. A common approach is to store previously processed eventId values and ignore duplicates.

Best Practices

Validate incoming callback payloads before processing.
Log callback deliveries for troubleshooting.
Store delivery events for auditing and analytics.
Process callbacks asynchronously where possible.
Return a 2xx response immediately after accepting the notification.
Use the Message Status API when historical delivery data is required.

Message Status API

If you need to retrieve the latest delivery information on demand, use the Message Status API.

GET /v1/messaging/sms/messages/{messageId}

This endpoint returns the current status and metadata for a specific message.

Message Status API

Retrieve the latest delivery status for a message.

Delivery Statuses

Learn about the SMS delivery lifecycle and status definitions.

Introduction

Authentication

Messaging

OTP Service

Workspace

Errors

FAQs

Supported Delivery Statuses

Event Types

Configuring a Callback URL

Single SMS

SMS Campaign

Example Callback Payload

Payload Fields

Event Metadata

Message Object

Delivery Lifecycles

Successful Delivery

Failed Delivery

Expired Message

Rejected Message

HTTP Requirements

Idempotency

Best Practices

Message Status API

Message Status API

Delivery Statuses

​Supported Delivery Statuses

​Event Types

​Configuring a Callback URL

​Single SMS

​SMS Campaign

​Example Callback Payload

​Payload Fields

​Event Metadata

​Message Object

​Delivery Lifecycles

​Successful Delivery

​Failed Delivery

​Expired Message

​Rejected Message

​HTTP Requirements

​Idempotency

​Best Practices

​Message Status API

​Related Resources

Message Status API

Delivery Statuses

Supported Delivery Statuses

Event Types

Configuring a Callback URL

Single SMS

SMS Campaign

Example Callback Payload

Payload Fields

Event Metadata

Message Object

Delivery Lifecycles

Successful Delivery

Failed Delivery

Expired Message

Rejected Message

HTTP Requirements

Idempotency

Best Practices

Message Status API

Related Resources