123eworld Knowledge Hub → Transactional SMS → Page 186
Transactional SMS API Webhooks: Delivery Receipts, Signatures, Retries and Event Processing
Complete developer guide to transactional SMS API webhooks, delivery receipts, signature verification, retries, duplicate events, ordering and reliable event processing.
Why webhooks matter
Transactional SMS is asynchronous. An API can accept a message immediately while the provider and carrier determine delivery later. Webhooks provide the event channel that tells the customer application what happened after submission. A good webhook design therefore becomes part of the message lifecycle, not an optional notification feature.
Event identity
Every webhook event should have a stable event ID. The customer application can store that ID and reject or ignore duplicate deliveries. The event should also contain the logical message ID so several provider events can be connected to one customer operation.
Signature verification
Webhook requests should be authenticated using a documented signature scheme such as HMAC. The signature should cover a canonical representation of the request and be verified before the application trusts the event body.
Retries
Webhook delivery should use bounded retries with backoff. Temporary customer endpoint failures should receive another attempt, while permanent authorization or validation failures should not cause an endless retry loop.
Acknowledgment
The customer webhook endpoint should acknowledge quickly after authenticating and durably accepting the event. Heavy business processing should normally happen asynchronously so a slow database or downstream service does not cause unnecessary webhook retries.
Ordering
Events can arrive late or out of order. Customers should not assume that a delivered event always arrives after every intermediate state. The event timestamp, sequence information where available and current message state should be considered together.
Duplicate events
At-least-once webhook delivery means duplicate events are normal. The receiving application should make event processing idempotent using event ID or an equivalent deduplication key.
Dead-letter handling
Events that cannot be delivered after the retry policy should enter a controlled dead-letter or failed-delivery state. Customers need a way to inspect and replay them safely.
Payload design
Keep webhook payloads focused on event identity, message identity, event type, timestamps and relevant status data. Avoid unnecessary sensitive content. Provide links or APIs for retrieving additional information when appropriate.
Testing
Test duplicate events, out-of-order events, signature failures, endpoint timeouts, 500 responses, slow processing and replay of previously delivered events.
Operations
Monitor webhook success rate, delivery latency, retry counts and oldest undelivered event. These metrics reveal customer integration health.
Developer takeaway
A reliable webhook system assumes networks fail, events repeat and order is imperfect. Authentication, idempotency and durable event processing are the foundation.
Event schema
A webhook event should include an event ID, event type, logical message ID, tenant-safe reference, event timestamp and schema version. Provider-specific fields can be nested so the core contract remains stable. This structure lets consumers build generic event processing while still allowing advanced integrations to inspect provider evidence.
Delivery endpoint lifecycle
Customer endpoints can be added, disabled, rotated or replaced. The platform should validate the endpoint configuration and store a clear active state. When an endpoint is disabled, queued webhook events should follow a documented policy rather than disappearing silently.
Retry schedule
Webhook retries should use exponential backoff and a maximum duration. The platform should record every delivery attempt with timestamp, HTTP outcome and latency. This makes it possible to explain why an event arrived late or was eventually moved to a failed-delivery state.
HTTP semantics
A successful HTTP response should mean the customer endpoint has durably accepted the event according to the platform contract. A 2xx response should not necessarily mean the customer's business logic has completed. Customers should acknowledge quickly and process asynchronously.
Event versioning
Webhook schemas need versioning just like synchronous APIs. Additive fields should normally be compatible, but changing event meanings or removing fields should require a deliberate version transition.
Consumer design
The receiving application should store the event ID before performing irreversible business actions. If the same event is delivered twice, the second copy should be recognized as already processed.
Privacy
Webhook payloads should contain only data necessary for the event. If message content is sensitive, customers can retrieve it through an authenticated API rather than receiving it in every callback.
Operational replay
A support or customer portal can offer controlled replay of failed webhook events. Replay should preserve the original event ID so consumers remain idempotent.
Capacity
Webhook delivery needs its own worker pool or concurrency controls. One slow customer endpoint should not block delivery to thousands of healthy customers.
Final implementation test
Create a test endpoint that deliberately returns 500, sleeps, returns duplicate acknowledgments and rejects signatures. Verify retries, event identity, latency metrics and final delivery state.
Consumer implementation
A receiving application should separate webhook authentication from business processing. The HTTP handler verifies the signature, validates the event schema, records the event ID and places the event into its own durable queue. It can then return a success response quickly. A worker performs the actual update to an order, account or notification record. This architecture prevents a slow business database from causing the sender to retry an event that was already safely received. It also makes duplicate handling explicit because the event ID can be checked before the business action is applied.
Event ordering strategy
If a customer needs state transitions in order, it should not rely on network arrival order. The application can compare event timestamps, sequence information or the current message state and ignore stale transitions according to a documented rule. For example, a delivered event should not be replaced by a later-arriving temporary submitted event. The platform should provide enough information for customers to make this decision without exposing internal provider complexity.
Replay and recovery
A replay facility is useful after a customer's webhook endpoint was unavailable. Replaying the original event rather than constructing a new event preserves the original event ID and timestamp. Customers can therefore process it using the same deduplication logic. Replay should be controlled, audited and rate-limited so a large backlog cannot overwhelm a customer endpoint.
Final reference
Webhooks are the bridge between asynchronous SMS processing and the customer's application. Treat events as durable, authenticated messages with explicit identity, retry and replay semantics.
Endpoint isolation
A webhook delivery system should isolate slow or failing customer endpoints from the rest of the platform. Per-endpoint concurrency and retry budgets prevent one customer's server from consuming all delivery workers. The platform can also pause an endpoint after repeated permanent failures while retaining its undelivered events for later inspection. This is a useful operational boundary because webhook delivery is a customer-controlled dependency.
Audit evidence
Keep an internal audit trail for endpoint changes, secret rotation, delivery attempts and replay actions. When a customer reports that an event was never received, support can inspect the timeline and determine whether the event was generated, authenticated, attempted, rejected, retried or finally abandoned. This evidence is often more useful than the raw webhook payload.
Developer pattern
The recommended consumer pattern is: verify signature, validate schema, check event ID, persist the event, acknowledge quickly, process asynchronously and make the business update idempotent. This pattern works across languages and frameworks and should be included in the developer documentation.
Knowledge-base conclusion
Webhook reliability is achieved through a complete event lifecycle. Authentication proves origin, event identity prevents duplicates, durable queues protect against downtime, and controlled retries recover temporary failures.
End-to-end engineering scenario
Production webhook testing should include an endpoint that deliberately becomes unavailable during a burst. The platform should queue events, retry them with backoff and recover after the endpoint returns. During the outage, healthy customer endpoints must continue receiving events. The test should also verify that the oldest pending event is visible in operations and that replay does not create a new event identity. This scenario demonstrates whether the webhook subsystem has genuine isolation and recovery rather than only a successful request path.
Advanced reference scenario
Webhook delivery should have a customer-visible delivery history showing event ID, event type, attempt count, last response and current state. This allows developers to diagnose their endpoint without opening support tickets. It should be possible to distinguish an event that was never generated from one that was generated but repeatedly rejected by the customer's server. The history should respect tenant permissions and avoid exposing secrets. Together with message status and request IDs, it creates a complete troubleshooting path from the original SMS submission to the customer's own event processor.
Continue through the 123eworld Knowledge Hub
Explore the complete 123eworld Knowledge Hub for practical SMS API, transactional messaging and developer architecture guides.
Visit 123eworld.com for messaging and digital communication services.