123eworld Knowledge Hub → Transactional SMS → Page 191
Transactional SMS API Webhook Security: HMAC Verification, Replay Protection and Event Deduplication
How to secure SMS API webhooks with signatures, timestamps, replay protection, secret rotation, duplicate handling and safe event processing.
Webhook threat model
Webhook endpoints are public-facing interfaces. Attackers may attempt to forge events, replay valid events or overload the endpoint. Signature verification and replay controls must therefore happen before business processing.
HMAC
Compute the HMAC over the exact documented payload representation and compare signatures using a constant-time comparison method. Canonicalization must be unambiguous.
Timestamp
Include a timestamp in the signed request and reject requests outside an accepted window. This reduces the usefulness of captured requests.
Replay store
For stronger replay protection, store event IDs or signed request identifiers for the acceptance window. A duplicate event should be recognized before business processing.
Secret rotation
Webhook secrets should support overlap during rotation. The receiver can temporarily accept both old and new secrets while the sender transitions.
TLS
Use HTTPS and validate certificates normally. Signature verification does not replace transport security.
Fast acknowledgment
Authenticate first, persist the event or enqueue it, then return a success response. Do not perform long business operations before acknowledgment.
Failure handling
Invalid signatures should normally receive a clear rejection without detailed information. Temporary processing failures can be retried by the sender if the event was authenticated but not durably accepted.
Observability
Log event ID, signature verification outcome and request ID without logging the secret or unnecessary sensitive payload.
Testing
Test forged signatures, old timestamps, replayed events, duplicate IDs, secret rotation and slow endpoints.
Developer takeaway
Webhook security is a combination of authenticity, freshness, deduplication and safe processing—not just one HMAC header.
Canonical signing
Define exactly which bytes are signed. JSON whitespace, encoding and header order can otherwise cause legitimate requests to fail verification.
Constant-time comparison
Signature comparison should use a constant-time method appropriate to the programming language. Avoid ordinary string comparison for security-sensitive signatures.
Replay window
Choose a replay window based on realistic network delay. A window that is too short can reject legitimate events; one that is too long gives captured requests more time to be reused.
Event ID storage
The receiver can store accepted event IDs with an expiry matching the replay window or longer if business processing needs longer duplicate protection.
Secret rotation
During rotation, the sender can sign with the new secret while the receiver temporarily accepts both. After confirmation, revoke the old secret.
Endpoint isolation
Use separate webhook credentials and endpoints for sandbox and production. Do not let a sandbox secret authorize production events.
Abuse protection
Even authenticated webhooks should have request-size limits, connection limits and rate controls. A valid secret does not mean unlimited traffic should be accepted.
Failure logging
Record signature failure counts and source metadata carefully. Do not log raw signatures or secrets.
Testing
Use forged bodies, modified headers, stale timestamps, replayed event IDs and rotated secrets.
Final implementation test
Verify that a valid event succeeds, a modified body fails, a stale event fails and a duplicate event is accepted only as a harmless duplicate.
Signature failure policy
Repeated invalid signatures can indicate a misconfigured customer endpoint or malicious traffic. The platform can rate-limit repeated failures and provide safe diagnostic information through the customer portal without revealing secret details.
Replay across regions
If webhook consumers run in multiple regions, replay protection must be globally consistent enough to prevent the same event from being processed twice. A regional-only cache can fail when the same event reaches another region.
Secret ownership
Customers should know which webhook secret belongs to which endpoint. During rotation, retain metadata about the old and new secret identifiers without exposing their values.
Final reference
Webhook security should remain effective even when the event is duplicated, delayed, replayed or delivered through another network path.
Replay cache design
The replay-protection store should be fast and bounded. Store a hash or event identifier rather than unnecessary payload data. The retention period should cover the signed timestamp window plus a safety margin.
Signature rotation
During secret rotation, the sender can include a secret identifier so the receiver knows which verification key to try. If this identifier is not part of the protocol, the receiver can attempt active keys in a controlled order.
Customer guidance
Documentation should provide complete verification examples for at least the major supported languages. A statement such as 'verify the HMAC' is insufficient because canonicalization and raw-body handling are common sources of mistakes.
Knowledge-base conclusion
Secure webhooks require correct cryptographic verification plus operational controls around replay, rotation, rate limits and duplicate processing.
End-to-end engineering scenario
Webhook security should be validated with raw-body tests because many frameworks parse and reserialize JSON before application code sees it. If the sender signs the original bytes and the receiver signs a reformatted representation, legitimate events will fail verification. Documentation should therefore show how to access the original request body. This is a small implementation detail with major practical impact, especially for developers using common web frameworks.
Advanced reference scenario
Webhook security testing should include a valid event that is modified by one byte after signing. The receiver must reject it. Then test a valid event outside the timestamp window and a valid event with an already processed event ID. Finally rotate the secret and verify that the old secret stops working after the overlap period. These tests demonstrate authenticity, integrity, freshness, deduplication and lifecycle management together rather than treating HMAC as an isolated feature.
Engineering decision guide
Webhook receivers should also protect their own downstream systems. After authentication and deduplication, events should enter a durable internal queue before triggering database updates, emails or other actions. If a customer's database is temporarily unavailable, the webhook handler can still acknowledge the sender after durable acceptance. This pattern prevents repeated sender retries from multiplying load on an already unhealthy downstream system and makes event recovery controllable.
Final architecture perspective
A final webhook security implementation should make verification a mandatory gateway step. Business handlers should never receive an event object that has not passed signature, timestamp and schema checks. After validation, the event ID should be persisted before irreversible business work begins. Secret rotation, endpoint changes and replay-protection configuration should all be auditable. This design gives customers a repeatable security pattern that can be implemented in any language and tested independently from the business application.
Practical engineering note
Webhook security should also include payload-size limits and endpoint rate controls. A valid signature does not make an oversized or abusive request harmless. Reject unreasonable payloads before expensive parsing and processing. Keep sandbox and production secrets separate and make endpoint ownership clear in the customer portal. During secret rotation, provide a safe overlap period and show the secret status without revealing the value. These controls make webhook security practical for long-lived integrations rather than treating it as a one-time configuration step.
Operational quality rule
Webhook event IDs should be globally unique within the sender's event domain and stable across retries. If the same event is delivered five times, all five requests should carry the same identity. This makes deduplication straightforward and prevents consumers from accidentally treating a retry as a new business event. The event schema should document this property explicitly rather than leaving it as an implementation detail.
Final knowledge-base takeaway
The webhook secret lifecycle should be documented alongside the endpoint lifecycle. When an endpoint is replaced, its secret should be rotated or retired according to policy, and old credentials should not remain active indefinitely.
Final safeguard
Webhook security should be included in penetration testing and integration tests. A secure design is one that remains secure when requests are forged, delayed, duplicated or modified.
Closing principle
Keep the security contract stable, testable and easy for developers to implement.
Final check
Audit every secret rotation.
Knowledge-base check
Test replay protection.
Last safeguard
Rotate secrets safely.
Final rule
Verify signatures.
Minimum safeguard
Always.
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.