How to Set Up SMS Delivery Status Callbacks

Choose the right callback use case

Start with one question: what should the callback change in your business? For order alerts, OTP delivery monitoring, or customer notifications, the answer is usually different. A store might care about a “delivered” status before sending a receipt. A bank might care about “failed” within 30 seconds, because a login code that never lands has a direct support cost.

That choice matters before you touch any settings. If you are documenting how to set up SMS delivery status callbacks, pick one workflow first and name the outcome in plain words: confirm delivery, spot failures, or track delays. One callback can support all three later, but the first version should answer one practical question.

Keep the scope narrow. A shipping team may only need status updates for the final SMS in the chain, not every reminder. A password-reset flow may need a callback only when the message is accepted or rejected, since “waiting” is not a useful state for a user who is already staring at a login screen.

Confirm your SMS provider’s callback model

Providers do not all speak the same language. Some use delivery receipts, some use webhooks, and some expose a status URL you must poll. Read the provider documentation for the exact event names and check which statuses are available.

One provider may send only final states. Another may send several updates for one message, and that changes how you store data later. If the provider supports both message-level and account-level callbacks, choose the one that matches the workflow you picked above. That detail saves confusion when the first test arrives and your app sees two events for one SMS.

There is a small trap here. Documentation often shows one JSON example, then the real account returns a slightly different shape for a different product tier. Compare the API notes, the dashboard labels, and any sample payloads before you wire the endpoint. If your provider offers a separate doc for delivery receipts, read that one too.

For teams that already handle other event-based systems, the pattern will feel familiar. The logic is similar to email webhook events for transactional emails: you need to know which events exist, which ones you care about, and which ones should never trigger customer-facing logic.

Prepare your public callback endpoint

Your callback endpoint needs a public HTTPS URL. Not a local port. Not a private IP. The provider must reach it from outside your network, and most SMS platforms will refuse plain HTTP in production. A common structure is /webhooks/sms/status, because it stays readable when logs and dashboards fill up.

Make the route stable. If you rename it every week, your dashboard settings will lag behind your code. Use one path, one method, and one handler for the first version. POST is the usual choice.

Accept incoming requests without blocking on slow work. The endpoint should read the request, validate the basics, and respond quickly. Heavy processing belongs in a job queue or background task. That way a burst of callbacks does not hold the connection open long enough to cause retries.

Test the route with a simple request body before you wire the provider. A 200 response on a dummy POST tells you more than a long debugging session later. If you are already comfortable with callback design from other channels, the same discipline shows up in web push notification best practices, especially around response timing and endpoint clarity.

Define the event payload your app needs

Do not store every field just because the provider sends it. Map the callback into your internal model first. At minimum, most teams need a message ID, recipient, status, timestamp, and error code field. Some providers also include carrier data, country, or a gateway reference, and those can help during support work.

Keep your mapping strict. If the provider calls a field sms_id and your database uses provider_message_id, write the translation once and reuse it. That prevents “works in staging” problems when a second integration arrives. A callback payload should update one SMS record, not create mystery duplicates.

Think about status history, not just the latest state. A single message can move from accepted to sent to delivered, or from queued to failed. If you collapse those into one text field too early, you lose the trail that explains why a code arrived late. That trail matters when a customer says, “I never got it,” and support needs more than a shrug.

For teams that already manage sender identity and message trust in email, the same kind of field discipline appears in DKIM SPF DMARC setup for transactional and other authentication work. The data model is different, but the habit is the same: capture the fields that prove what happened.

Register the callback in your SMS settings

Most providers let you enter the callback URL in a dashboard screen or through an API setting. Some require account-level setup first, then message-level overrides later. Look for labels such as delivery callback, status callback, webhook URL, or receipt URL. The wording varies, but the goal does not.

Use the provider’s exact field names when the dashboard asks for them. A URL for delivery events may be separate from a URL for inbound replies. If you mix the two, your app may receive data it cannot interpret. That is a simple mistake, and it is common enough to deserve a checklist item.

Permissions can matter here. An admin-only account might be needed to change callback settings, or an API key may need a write scope. If the dashboard asks for verification before saving, finish that step before shipping code. Otherwise the callback can look “configured” while no request ever reaches your endpoint.

Once the setting is saved, send one message from the same account or tenant you use in production. A callback configured in the wrong workspace is a boring failure, which is good only in the sense that boring failures are easier to fix than silent ones.

Secure and authenticate incoming requests

Never trust the request body by default. Check for a shared secret token, a signature header, IP allowlisting, or a signed timestamp, depending on what your provider supports. One of those methods may be enough on its own, but many teams combine two checks for better control.

Signature validation should happen before any database write. If the signature fails, reject the request and log the attempt. If the provider includes a timestamp, compare it to your server clock to reduce replay risk. A callback sent yesterday should not be accepted today just because the format still looks valid.

IP allowlisting sounds simple until a provider changes infrastructure. Use it only if the provider publishes fixed ranges and keeps them updated. Secret tokens are usually easier to maintain, and signature validation is stronger than a static token alone. A quick aside: if your security team asks for all three, they are not being dramatic.

Do not forget transport protection. HTTPS is the baseline. Certificates must be valid, and redirects should be avoided if the provider does not follow them. This is one of those steps that feels dull until the first bad actor tries to post fake delivery updates into your system.

Store delivery updates in your system

Store each callback against the original SMS record using the provider’s message ID and your own internal ID. That link is the key to every later report. Without it, you end up searching logs by phone number, which gets ugly quickly once multiple campaigns use the same recipient.

Write status changes in order. If the provider sends queued, then sent, then delivered, keep that sequence. If an older callback arrives late, ignore it or compare it against the latest known state before saving. A delayed “sent” update should not overwrite a newer “delivered” status.

Use timestamps for both provider time and local receive time if you can. The first helps with external tracing. The second helps with incident response when your own server was slow or briefly unavailable. That combination gives you enough detail to answer a support ticket without guessing.

A simple table can help the team agree on state handling:

Think about downstream reporting too. If your customer success team wants to see delivery rates by campaign, store a campaign ID alongside the message. If finance wants to reconcile OTP volume, keep the template name. Small fields save long meetings.

Set up alerts and fallback handling

Callbacks fail in predictable ways: the endpoint returns 500, the signature check starts rejecting everything, or the provider stops sending requests for a specific account. Put an alert on each of those cases. If no callback arrives for a message after a reasonable window, that is a signal worth paging or at least emailing.

Set one alert for “callbacks stopped,” another for “validation failed,” and a third for “error status received.” Those are three different problems. A missing callback may mean network trouble. A failed status may mean the carrier rejected the SMS. A validation failure may mean your secret rotated and the provider was not updated.

Have a fallback path. If the provider supports polling, use it when callbacks are missing or delayed. Polling should not be your first choice, but it is better than blind spots. Some teams poll only for high-value messages such as OTPs or payment confirmations, which keeps the extra traffic contained.

If your team already watches deliverability signals in other channels, similar habits apply in email bounce handling best practices. The channel is different, but the operational response is the same: watch for error states, log them cleanly, and decide when to retry, alert, or stop.

Document the fallback rule in one place and make support read it. A customer should not have to guess whether a failed SMS will retry automatically. If the answer is “not for OTPs,” say that plainly. If the answer is “poll after 10 minutes,” write the exact number once and use it everywhere.