Skip to main content
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

StatusDescription
SUBMITTEDMessage accepted by Zeckta and queued for delivery.
SENTMessage successfully submitted to the upstream carrier.
DELIVEREDMessage confirmed delivered to the recipient handset.
FAILEDDelivery attempt failed.
UNDELIVERABLEDestination number could not be reached.
EXPIREDMessage validity period expired before delivery.
REJECTEDMessage 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 TypeDelivery Status
MESSAGE_SUBMITTEDSUBMITTED
MESSAGE_SENTSENT
MESSAGE_DELIVEREDDELIVERED
MESSAGE_FAILEDFAILED
MESSAGE_UNDELIVERABLEUNDELIVERABLE
MESSAGE_EXPIREDEXPIRED
MESSAGE_REJECTEDREJECTED

​
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

FieldDescription
eventIdUnique identifier for the callback event.
eventTypeDelivery event being reported.
timestampISO-8601 timestamp when the event occurred.

​
Message Object

FieldDescription
message.uuidUnique identifier of the SMS message.
message.srcSender ID used for the message.
message.destRecipient phone number.
message.statusCurrent delivery status.
message.segmentsNumber of SMS segments consumed.
message.unitsBilling units consumed.
message.attemptsNumber of delivery attempts made.
message.costFinal 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.