Transaction Status Webhook

After you send an SMS, the telecom network reports back whether each message was delivered. The Comms platform relays that report to your system as an HTTP POST request — for this API, you don't call an endpoint, you create one to receive data instead.

How it works

1. You configure a webhook URL in the Comms platform under Settings > API Settings.
2. When the telecom network reports a delivery outcome for a message you sent, Comms sends a POST request with a JSON body to that URL.
3. Your endpoint reads the payload, persists or acts on it, and responds.

Reports arrive asynchronously, sometime after the original SendSms call returned. Match a report back to the message it belongs to using MsgFollowUpUniqueCode — the same code returned in the SendSms response.

Endpoint requirements

• Accept POST requests with a JSON body (Content-Type: application/json).
• Respond with HTTP 200 as soon as you've received the payload. If persisting the report is slow (e.g. a database write or downstream call), acknowledge first and do the slow part asynchronously so the webhook call doesn't time out.
• The response body isn't inspected — a plain 200 OK with no body, or a small JSON acknowledgement like {"success": true}, both work. See Code Examples for working endpoints in several languages.

Securing your endpoint

This URL is public — Comms must be able to reach it, but so could anyone else who finds it. Don't trust it blindly: restrict it to Comms' IP range, or register a URL with an unguessable path segment or token, so third parties can't submit fake delivery reports.

This Status is not the request Status

The Status field here reports the delivery outcome of an individual message (e.g. delivered to the handset). It's unrelated to the request-level Status/Failed contract used by SendSms and Balance — this webhook call has no such contract. See Error Handling for that one.

Payload fields

MsgFollowUpUniqueCodestring

The same unique tracking code returned in the original SendSms response. Use it to match this report to the message you sent.

---

numberstring

The recipient phone number this report is for, in the same international format you sent it in.

---

Statusstring

Delivery outcome reported by the telecom network for this message, for example "Success".

---

deliveryDatedate

ISO 8601 timestamp of when the network reported the outcome, for example "2026-08-05T08:58:23.679Z".

---

Example payload

{
  "MsgFollowUpUniqueCode": "0800fc577294c34e0b28ad2839435945",
  "number": "256759001234",
  "Status": "Success",
  "deliveryDate": "2026-08-05T08:58:23.679Z"
}

Next steps

• Code Examples — receiving endpoints in several languages and frameworks.
• Sending SMS — where MsgFollowUpUniqueCode comes from.
• Error Handling — troubleshooting SendSms and Balance request failures.