123eworld Knowledge Hub → SMS API → Page 296
SMS API Webhooks: Designing Reliable Delivery Status Callbacks
A practical developer reference designed to solve real implementation and production problems around sms api webhooks: designing reliable delivery status callbacks.
Why webhooks are essential
SMS delivery is asynchronous. An API response can confirm that a messaging platform accepted a request, but it cannot normally prove that the handset received the message. Webhooks give customer applications a way to receive later status events without continuously polling the status endpoint.
Logical message lifecycle
A webhook should refer to the same logical message ID returned by the send API. Provider message IDs and attempt IDs can be included as diagnostic identifiers. This makes the event useful across retries and provider changes.
Event structure
A practical event should include event ID, message ID, event type, status, event timestamp and a version. Optional provider diagnostics can be included without making provider-specific fields mandatory for every customer.
At-least-once reality
Webhook delivery should normally be designed as at-least-once. The receiver must tolerate duplicate events because network failures can occur after the receiver processed an event but before the sender received an acknowledgement.
Ordering
Events can be delayed or arrive out of order. The customer application should use event timestamps and documented state-transition rules rather than assuming network arrival order is business order.
Fast acknowledgement
Webhook receivers should authenticate the request, persist or enqueue the event and return an acknowledgement quickly. Long business processing inside the HTTP request increases timeout and duplicate risk.
Queue-based processing
A receiver can put validated events into an internal queue and process them asynchronously. This protects the public endpoint during bursts.
Versioning
Version webhook schemas deliberately. Adding optional fields is usually easier than changing field meaning. Preserve compatibility for existing integrations.
Observability
Track webhook delivery attempts, response codes, latency, retry counts and dead-letter events.
Testing
Test duplicate events, delayed events, invalid payloads, receiver downtime and burst delivery.
Reference architecture
Provider receipt → normalization → logical event creation → durable webhook queue → signed delivery → customer acknowledgement → retry or completion.
Production checklist
Use stable IDs, explicit event types, schema versions, signatures, retry policy, dead-letter handling and delivery metrics.
Security and privacy
Treat phone numbers, message content, credentials and delivery data as sensitive operational information. Avoid unnecessary logging and ensure tenant authorization is applied before data access.
Production reliability
Design for timeouts, duplicates, retries, provider failures and delayed events. A messaging platform is asynchronous infrastructure, so success-path testing alone is insufficient.
Developer-first principle
The public API should hide unnecessary telecom complexity while exposing enough structured information for developers to build correct integrations.
Related 123eworld guides
Explore the 123eworld SMS & WhatsApp Knowledge Hub for related developer, API, routing and production guides.
Webhook delivery contract
Define the webhook contract as an asynchronous event interface rather than as an extension of the send API. The send response should provide the logical message ID and tell the developer that later lifecycle information is delivered through the status API and webhook. The webhook event should be self-contained enough to process without making an immediate status lookup. Include a stable event ID, logical message ID, event type, event creation time and schema version. Provider-specific identifiers can be optional diagnostic fields. This contract lets customers build reliable consumers without learning how the underlying SMS provider works.
State transitions
Document which event types are terminal and which are intermediate. A message can move from accepted to queued to submitted and finally to delivered or failed, but real-world provider evidence can arrive late. The platform should define how late evidence affects the current state. Keep the event history immutable even when the current logical state is updated. This allows support teams to investigate an apparent contradiction without losing the original provider evidence.
Consumer design
The customer's webhook handler should authenticate the event, validate the schema, persist the event ID and enqueue business processing. It should then return a success response quickly. Business actions such as updating a CRM, sending an email or changing an order should happen asynchronously. If processing fails, the customer can retry from its own queue without asking the messaging provider to resend the event.
Delivery semantics
Document whether events are at-least-once and whether ordering is guaranteed. In most distributed systems, customers should assume duplicates and possible reordering. A developer who implements a webhook consumer with a simple 'process every request' rule can accidentally send duplicate emails or change a database record repeatedly. The reference implementation should show event-ID deduplication and state-aware processing.
Failure recovery
If a customer endpoint remains unavailable, webhook attempts should eventually move to a durable failed-delivery state. The platform should expose a way for authorized users to inspect failed deliveries and replay them. Replay must be controlled and auditable. It should not create a new logical SMS message; it should create another attempt to deliver the same event.
Testing scenarios
Test successful delivery, slow responses, connection resets after processing, duplicate events, out-of-order events, schema-version changes and customer endpoint recovery. Load-test webhook bursts separately from SMS submission because delivery receipts can arrive in concentrated waves after a provider recovers.
Webhook schema design
Use a top-level schema version and event type rather than allowing the meaning of fields to change silently. Event types should be specific enough for developers to build deterministic handlers. Include timestamps in a documented format and distinguish event creation time from provider event time when both exist. This is important because a receipt can arrive much later than the underlying delivery event.
Provider normalization
The webhook layer should normalize provider callbacks before creating customer-facing events. Provider-specific receipt codes, carrier identifiers and diagnostic values can be retained internally, while the public event exposes a stable status vocabulary. This keeps customers insulated from provider migrations.
Delivery guarantees
A webhook platform should clearly document what an acknowledgement means. If the endpoint returns a successful response, the event should be considered accepted for that delivery attempt. It should not mean that the customer's downstream business processing completed. This separation makes retries and customer-side queues much easier to reason about.
Incident response
When webhook delivery degrades, operators should see which tenants or endpoints are affected, the oldest pending event age, current retry volume and last successful acknowledgement. Avoid using only aggregate success rate because one large customer can hide a problem affecting smaller tenants.
Webhook endpoint onboarding
The onboarding process should give customers a test-event function or clearly documented sample payload. Before production activation, the customer can verify DNS, TLS, authentication and event processing. A test event should be distinguishable from a real delivery event so it cannot trigger business actions accidentally. Production activation should be explicit and auditable.
Schema evolution
When adding fields, prefer optional additions and preserve existing field names and meanings. If an event requires a fundamentally different structure, publish a new schema version. Give customers a migration window and maintain both versions where practical. Never silently reinterpret a field based on event type.
Webhook performance target
Define a recommended response time for customer endpoints and explain that the platform may retry slow responses. Encourage customers to enqueue events and acknowledge quickly. This one architectural recommendation prevents many webhook reliability problems.
Webhook event examples
A production guide should show the difference between a delivery event and a message-status response. The webhook event represents an asynchronous occurrence; the status API represents current state. If a customer receives a delivered event and later queries the status API, both should refer to the same logical message. This consistency prevents developers from maintaining two unrelated state machines.
Consumer deduplication pattern
A robust receiver can use a table keyed by event ID with a unique constraint. Insert the event, commit the transaction and then publish it to an internal business queue. If the event ID already exists, return success without creating another business action. This pattern is simple, durable and easy to explain.
Monitoring dashboard
Track delivery success percentage, p95 acknowledgement latency, retry count, oldest pending event, dead-letter count and endpoint-level failures. These metrics show both platform health and customer endpoint health. Alert on sustained degradation rather than every individual timeout.