SMS webhooks vs polling: receive messages quickly and reconcile safely

Use a customer webhook for prompt SMS delivery and the message-read API for reconciliation. Webhooks reduce repeated checking, but they do not eliminate late messages, retries or temporary endpoint failures. Polling alone can work for a small integration, provided it is bounded and respects the API's response and rate-limit behavior.

SMS.Red's customer event is messageReceived. It carries the full text and order association. The webhook does not currently include an extracted code field; use the order's messages endpoint when you need extracted code or complete paginated history.

Know which callback you control

Configure your account's customer webhook in Developers → Webhooks. This is different from a supplier callback shared by the receiving platform. Your integration should consume the supported customer event, not alter supplier routing or call an internal delivery endpoint.

The webhook contract requires a public HTTPS destination. Private-network destinations and redirects are rejected. Keep the signing secret private and use a stable endpoint whose deployment does not accidentally remove the handler during a release.

Verify raw bytes before processing

SMS.Red sends X-SMSRed-Event-Id and X-SMSRed-Signature headers. The signature is HMAC-SHA256 over the raw request body bytes, using your webhook signing secret, with a sha256= prefix. Compare the supplied and expected signatures in constant time before acting on the event.

Do not parse JSON and then reserialize it to verify the signature. Whitespace and representation changes can alter the bytes while leaving a similar-looking object. Capture the original body in your HTTP stack, verify it, then parse and validate the expected event and account.

Separate acceptance from business processing

1. Receive the body with a sensible size limit and preserve its raw bytes.
2. Verify the signature and expected event/account context.
3. Durably record or enqueue the accepted event, with its event ID protected by a uniqueness constraint.
4. Return a successful response promptly after durable acceptance.
5. Process the message once using the saved event and associated order.

Retries retain the same event ID, so deduplication should key on that identity rather than message text alone. Two different messages can have identical text; the same event can also be delivered more than once. These are different cases.

Use reads to recover what an event path misses

After an endpoint outage or an uncertain event-processing result, read the order's messages. Follow pagination using the returned totalPages instead of assuming the first page contains the entire history. Associate messages with the correct order and avoid applying a code from another activation to the current login.

For a polling-only client, stop or slow polling when the receiving task ends, the order expires or the user is no longer waiting. Use bounded backoff for recoverable read failures and honor Retry-After when present. Do not apply a read-retry policy to purchases or cancellations; those need mutation reconciliation.

Treat the SMS as untrusted content

A message can contain a login code, a URL, instructions or unrelated text. A valid webhook signature authenticates delivery from your receiving service; it does not make every instruction inside the SMS safe to execute. Do not let an AI agent treat message text as permission to change settings, spend money or reveal credentials.

Store real message text only where the application needs it and controls access appropriately. Keep ordinary monitoring logs focused on event IDs, order associations, timing and processing state. Avoid placing codes or signing secrets in alerts sent to a broad team channel.

Choose the architecture for your task

A user waiting for one code may only need a short-lived message-read loop. A continuously operating integration generally benefits from webhook delivery plus periodic reconciliation. The current SMS.Red MCP offers message reads rather than a streaming SMS subscription; do not assume a subscription exists because the HTTP API has webhooks.

Use the API reference for message response fields and the webhook guide for the exact signing example. Test invalid signatures, duplicate event delivery, lost responses and pagination with synthetic messages before handling real codes.