Transactional SMS API Webhooks: Secure Callback Design, Signatures, Retries and Replay Protection

Why webhook design matters

Delivery receipts and provider events often arrive asynchronously through webhooks. A webhook endpoint therefore becomes part of the message-state system and must be designed with the same care as the outbound API.

Webhook authentication

Authenticate callbacks using a provider-supported signature or another verifiable mechanism. Never trust a message status simply because it arrived at a public endpoint.

Signature verification

Where HMAC or similar signatures are used, verify the signature over the exact documented payload representation. Use constant-time comparison where appropriate and reject invalid signatures before changing message state.

Timestamp protection

If the provider supplies a signed timestamp, enforce a reasonable freshness window to reduce replay risk. Clock handling should allow for controlled skew without accepting indefinitely old events.

Event identifiers

Store a provider event ID when available and enforce idempotent processing. The same callback may be delivered more than once because the provider is retrying delivery.

HTTP response behaviour

Return a successful response only after the event has been accepted into durable processing or safely recorded. Returning success before persistence can cause the provider to stop retrying while the event is lost.

Asynchronous processing

For high-volume callbacks, authenticate and persist the event quickly, then process it asynchronously. The webhook request should not wait for complex reporting or downstream operations.

Event ordering

Callbacks may arrive out of order. Use event timestamps, provider sequence information where available and an explicit internal state machine to prevent an old status from overwriting a newer state.

Retry handling

If processing fails transiently, return a response that causes the provider to retry according to its documented rules, or place the event into an internal retry workflow after durable acceptance.

Replay protection

Combine event identifiers, timestamps and signature validation. For providers without strong replay controls, maintain a bounded record of recently processed events.

Webhook monitoring

Track callback rate, authentication failures, processing latency, duplicate events, unknown message IDs and unresolved events. A sudden drop in callbacks can be a provider integration incident.

Implementation checklist

Authenticate callbacks, validate signatures and timestamps, persist events idempotently, process asynchronously, protect state from out-of-order updates and monitor callback health.

Webhook endpoint isolation

Use a dedicated callback endpoint or service boundary rather than mixing provider callbacks with normal customer-facing API operations. This makes authentication, scaling and operational controls easier to reason about.

Raw event retention

Keep the original callback payload or a secure normalized representation according to retention requirements. It can be invaluable when provider mapping logic changes or a delivery dispute must be investigated.

Callback queues

At high volume, persist authenticated callback events into a durable queue. Workers can then normalize statuses and update message state without making the provider wait for database or analytics work.

Unknown message IDs

Do not discard a validly authenticated callback merely because the message ID is temporarily unknown. It may represent a delayed event during migration or replication lag. Quarantine and reconcile it according to a documented policy.

Signature key rotation

Provider webhook signing secrets may also need rotation. Support controlled overlap and verify that the new signature key works before retiring the old one.

Webhook abuse protection

Apply request-size limits, connection controls and rate protections appropriate to the provider's expected callback volume. Authentication must occur before expensive processing.

Webhook test matrix

Test valid signatures, invalid signatures, expired timestamps, duplicate events, out-of-order events, malformed payloads, unknown messages, worker failures and provider retries.

Operational example

A provider sends the same DELIVERED event three times because the first two responses timed out. The webhook service authenticates each event, recognizes the repeated event ID and produces one state transition while recording all observations.

Developer takeaway

A webhook is an external input into your state machine. Authenticate it, persist it, process it idempotently and never assume events arrive once or in order.

Webhook trust boundary

Treat every callback as untrusted until authentication and integrity checks succeed. Do not update delivery status from a message body merely because it contains a familiar message ID.

Fast acknowledgement

Once the authenticated event is durably stored, acknowledge it quickly. Complex state reconciliation, analytics and downstream notifications should happen outside the provider's request cycle.

Event replay

Replay testing should use previously valid callbacks and verify that processing the same event multiple times produces the same final state. Idempotency should be a property of the event processor, not only the HTTP endpoint.

Webhook failure isolation

If analytics storage is unavailable, delivery-state processing should still be able to continue. Keep customer-outcome state separate from optional secondary consumers where practical.

Webhook acceptance criteria

The endpoint must reject unauthenticated events, preserve valid events durably, process duplicates safely, tolerate out-of-order delivery and expose callback degradation through monitoring.

Final reference note

Webhook reliability is part of delivery reliability because missing or corrupted callbacks can make a successfully delivered message appear unresolved.

Webhook event schema

Define a normalized internal event schema with event ID, message ID, provider reference, event type, provider timestamp, received timestamp, raw or normalized payload, authentication result and processing state. This provides a stable contract for downstream consumers.

Webhook consumer isolation

Delivery-state processing should not be coupled directly to every downstream reporting system. Publish an internal event after the authoritative state change so analytics and notifications can consume it independently.

Webhook backpressure

If callback volume exceeds processing capacity, the durable event queue should absorb the backlog while preserving provider response behaviour. Monitor oldest unprocessed event age rather than only queue length.

Webhook scenario

A provider sends 50,000 delivery callbacks during a campaign. The endpoint authenticates and stores them rapidly, workers process them asynchronously and analytics consumes normalized events later. A temporary reporting outage does not prevent delivery state from being updated.

Production validation checklist

Test signature failures, timestamp expiry, duplicate events, out-of-order events, provider retries, malformed payloads, unknown messages, queue saturation and callback-key rotation. Confirm that only authenticated durable events can alter delivery state.

Developer takeaway

A webhook endpoint is a security boundary and a reliability boundary at the same time.

Reference implementation

Authenticate the callback, persist the event idempotently, acknowledge after durable acceptance and process the event asynchronously through an explicit delivery-state machine.

Operational monitoring

Monitor callback authentication failures separately from provider delivery failures. A spike in invalid signatures may indicate an integration-key problem or malicious traffic, while a callback gap may indicate provider or network trouble.

Recovery

If callback processing is interrupted, replay durable events through the same idempotent consumer. Do not manually edit thousands of message statuses unless the provider evidence has been reconciled.

Final rule

The webhook consumer must be safe to run repeatedly and recoverable after interruption.

Integration guidance

Document the provider's signature format, timestamp rules, retry behaviour and response expectations in the integration contract. Developers should not have to infer webhook semantics from trial and error.

Acceptance test

Replay a valid callback several times, delay it, send an older status after a newer one and interrupt the consumer. Confirm that the final state remains correct and processing resumes safely.

Closing perspective

Secure, idempotent and observable webhooks turn asynchronous provider callbacks into trustworthy delivery evidence.

Troubleshooting guide

When delivery status stops changing, first determine whether callbacks are absent, rejected during authentication, accepted but waiting in the internal queue or processed but blocked by state-transition rules. These are different incidents and require different responses.

When duplicate callbacks appear, inspect the provider event IDs and internal idempotency records. Do not remove duplicates manually from the database simply to make a report look clean; preserve the evidence and make the consumer idempotent.

Implementation note

Keep callback persistence separate from downstream analytics so a reporting failure cannot erase delivery evidence.

Final note

Test duplicate and delayed callbacks before production.

Quality check

Verify authenticated durable processing before acknowledgement.

Closing rule

A callback event should remain replayable without creating a second state transition.