Choosing Twilio SMS Delivery State: StatusCallback Webhooks vs. Polling Messages

Decision and Constraints

In a production service you must know whether an SMS has been delivered, undelivered, or failed. The requirements are:

• At‑least‑once delivery guarantees.
• Idempotent processing of duplicate callbacks.
• Signature validation of each webhook.
• No reliance on undocumented fields.

Option Comparison

Option	Latency	State coverage	Main risk
StatusCallback webhooks	near real time	queued, sent, delivered, undelivered, failed, channel‑specific	missed, duplicated, retried, out‑of‑order callbacks
Poll Messages resource	poll‑interval delayed	current snapshot only	rate limits, stale data
Webhooks + reconciliation	best effort	authoritative after merge	more moving parts, extra storage

Trade‑offs

Webhooks push state changes instantly but are at‑least‑once and may arrive out of order, so you must persist the event before acknowledging and ignore older transitions.

Polling is simpler, requires no inbound endpoint, but only gives a snapshot, can hide intermediate states, and consumes API quota; it is best used for audits, not user‑facing state.

Concrete Implementation

When creating a message, set the StatusCallback to an HTTPS URL and use POST if your handler expects a body.

POST /messages
{
  "To": "+15551234567",
  "Body": "Hello",
  "StatusCallback": "https://example.com/twilio/callback",
  "StatusCallbackMethod": "POST"
}

In the callback handler you must:

1. Re‑create the exact request URL (including query string) that Twilio used.
2. Validate the X‑Twilio‑Signature header against your Account Auth Token.
3. Read MessageSid, MessageStatus (or legacy SmsSid/SmsStatus) and any ErrorCode.
4. Persist the event (e.g., write to a durable store) keyed by MessageSid.
5. Return a 2xx response quickly; defer heavy work to a queue.

Idempotency is achieved by storing the MessageSid and the highest status rank observed (queued < sent < delivered; failed/undelivered are terminal). Subsequent callbacks with the same MessageSid and a lower rank are ignored.

Validation Steps

1. Use a Twilio test account and expose a local HTTPS endpoint with a tunnel (e.g., ngrok).
2. Send a test SMS to a supported phone number and force a normal delivery and a failure path (invalid number, expired validity).
3. Verify that each expected callback arrives, that the signature header validates, and that duplicate callbacks are de‑duplicated.
4. After callbacks are received, call GET /2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}.json and compare the MessageStatus, ErrorCode and timestamps with your stored state.
5. Confirm the SDK version matches the current REST API; check the helper‑library documentation for StatusCallback parameter names.

Limitations and Practical Checks

• Callbacks are not exactly‑once; duplicate events are expected and must not cause side effects.
• Signature validation fails if the URL, query string, POST body, or auth token changes; proxies and URL rewrites are common culprits.
• SMS does not provide read receipts; do not design flows that require a read event unless the channel supports it.
• When using Messaging Services or sender pools, callback configuration can be overridden at the service level; verify the effective precedence.
• Helper‑library types and option names vary by SDK version; always reference the current Twilio API docs.

After you have implemented the webhook flow, you can optionally run a reconciliation job that periodically GETs the Messages resource for any MessageSid that has not emitted a callback, ensuring no delivery state is missed.