123eworld Knowledge Hub → Transactional SMS → Page 156
Transactional SMS API Webhooks: Event Delivery, Signatures, Retries, Ordering and Reliable Status Notifications
Design reliable transactional SMS webhooks with event contracts, signatures, retries, ordering, idempotency, delivery guarantees and production troubleshooting.
Why webhooks matter
Transactional SMS is asynchronous. The API can accept a message before a provider has attempted it and long before a handset outcome is known. Webhooks provide an event-driven way for customers to learn about status changes without continuously polling the API. A well-designed webhook system therefore becomes part of the public product contract rather than an optional notification feature.
Webhook event model
Define stable event names and a consistent envelope containing event ID, event type, creation time, message ID and relevant status information. Keep the logical message ID separate from the webhook delivery ID. This lets the same business message generate several lifecycle events while each delivery remains independently traceable.
Delivery guarantees
Do not promise exactly-once webhook delivery unless the infrastructure genuinely provides it. The safer contract is usually at-least-once delivery combined with a stable event ID so customers can deduplicate. A webhook consumer should treat repeated delivery as normal behaviour rather than as an exceptional failure.
Signature verification
Sign webhook payloads so customers can verify that the event came from the messaging platform and was not modified. Use a documented canonical representation, timestamp and replay window. Provide official examples and SDK helpers because signature failures often arise from serialization differences rather than cryptographic problems.
Retries and backoff
If the customer endpoint is unavailable, the platform should retry according to a bounded schedule. Exponential backoff with jitter reduces synchronized retry pressure. Keep retry policy separate from message-delivery retry policy because a webhook failure does not mean the SMS itself failed.
Ordering
Events can arrive out of order when several workers deliver callbacks concurrently. Include event creation time and a monotonic sequence where the business contract requires ordering. Consumers should be able to ignore an older status after a newer terminal state has already been recorded.
Idempotent consumers
Customers should store webhook event IDs or another stable deduplication identity. A repeated 'delivered' event must not create duplicate invoices, notifications or database updates in the customer application.
Failure isolation
One customer's unavailable webhook endpoint should not block message processing or other customers' callbacks. Use tenant-aware queues and bounded concurrency. A persistently failing endpoint can be moved to a controlled retry or suspended state while the message platform continues operating.
Observability
Track webhook success rate, latency, retry count, endpoint response codes and delivery backlog. Correlate webhook events with message ID and provider attempt ID. Support teams should be able to determine whether a message was delivered but the customer's callback endpoint failed.
Security and privacy
Send only the fields the customer needs. Do not put credentials or unnecessary message content into webhook payloads. Protect webhook configuration, restrict destination changes and audit administrative changes.
Testing
Test duplicate events, delayed events, out-of-order delivery, endpoint timeouts, 4xx and 5xx responses, signature failures and customer endpoint recovery. Use a test endpoint that intentionally fails so retry behaviour can be observed.
Production checklist
Define event schema, delivery semantics, signature method, retry schedule, ordering behaviour, deduplication guidance, tenant isolation, observability and retention. Version webhook contracts when a breaking payload change is required.
Developer takeaway
Reliable webhooks are an asynchronous API in their own right. Make them secure, repeatable and observable so customers can build business workflows without depending on constant polling.
Implementation architecture
Implement webhook delivery through a durable event queue. Persist the event before attempting the customer callback, assign a stable event ID, sign the payload, deliver with bounded concurrency and record every attempt. A failed callback should be retried independently from the SMS provider workflow. This separation is important: a customer endpoint outage must not cause the platform to resend the SMS itself.
Operational reference
A webhook consumer should acknowledge only after it has safely persisted the event or completed the required idempotent business action. Returning success before durable processing can cause the platform to stop retrying even though the customer's application lost the event.
Operational reference
Webhook configuration should be tenant-scoped and auditable. Changing a callback URL while messages are in flight should have deterministic behaviour, and retries should use the documented endpoint-selection rule.
Operational reference
Keep webhook event versions explicit. A new status field can be additive, but changing the meaning of an existing status should require a new contract version and migration guidance.
Production checklist
Production check: verify duplicate webhook delivery, signature validation, out-of-order events, endpoint failures, tenant isolation and retry backlog recovery.
Additional implementation guidance
Webhook delivery should be isolated from the provider delivery path. A callback outage is a customer-integration problem, not an instruction to retry the SMS. Keeping separate queues, metrics and retry policies makes this distinction explicit.
Additional implementation guidance
Event persistence should happen before callback delivery. If a worker crashes after receiving a provider event but before creating a durable customer event, the platform may lose a status transition. Persisting first gives the delivery worker a reliable source.
Additional implementation guidance
Webhook endpoint changes should be versioned and audited. If a customer changes its URL, the platform should have a documented rule for whether pending retries use the old endpoint or the new endpoint. This matters during migrations.
Additional implementation guidance
Customers should be able to test webhook signatures and event handling without generating real production traffic. A test event facility can reduce integration errors and make deployment safer.
Additional implementation guidance
Monitor the age of the oldest undelivered webhook. This is often more useful than a simple success percentage because a callback system can show high success while a subset of customers experiences long delays.
Additional implementation guidance
Webhook retries should stop after a documented policy and move into a recoverable state. Customers should have a way to identify failed deliveries and request controlled replay rather than depending on an operator to search logs.
Additional implementation guidance
Keep the webhook event contract independent from internal queue names and provider-specific states. Customers should receive stable business events even when the internal provider architecture changes.
Reference architecture note
Webhook replay tools should require explicit tenant authorization and should show event identity before execution. A replay should resend the same event ID unless the customer explicitly requests a new delivery identity. This distinction prevents a replay from being mistaken for a new business event. The platform should also record who initiated the replay, when it occurred and which endpoint was targeted. These controls make operational recovery auditable and reduce the risk of an operator accidentally creating duplicate customer actions.
Advanced production guidance
Webhook security should include endpoint ownership. When a customer changes a callback URL, the platform should avoid immediately trusting an unverified destination if the workflow involves sensitive events. Verification can use a challenge or an administrative approval step depending on the product.
Advanced production guidance
Webhook payloads should be intentionally small. Customers can retrieve additional message information through authenticated APIs when necessary. Smaller payloads reduce privacy exposure and make delivery more reliable.
Advanced production guidance
Event retention should be long enough to support customer retry and reconciliation but not indefinite by default. Keep the event ID and delivery history according to documented retention rules.
Advanced production guidance
SDKs should expose webhook verification and event parsing helpers. This reduces the chance that customers implement signature validation or deduplication incorrectly.
Engineering reference
Webhook delivery should expose a clear distinction between endpoint rejection and platform failure. A customer endpoint returning 410 may mean the subscription should be disabled, while a 503 normally means retry later. Classifying responses correctly prevents endless retries to permanently invalid destinations.
Engineering reference
Webhook event generation should be based on durable message-state transitions. If two internal workers observe the same transition, an event ID or transactional outbox prevents two logically identical events from being created.
Engineering reference
During incident recovery, replay webhook events only after the underlying message state is correct. Replaying an event before reconciliation can cause a customer application to act on a status that later changes.
Continue through the 123eworld Knowledge Hub
Explore the complete 123eworld Knowledge Hub for practical SMS API, transactional messaging, queue, security and developer architecture guides.
Visit 123eworld.com for messaging and digital communication services.