123eworld Knowledge Hub → SMS API → Page 297
SMS API Webhook Security: Signatures, Authentication, Replay Protection and Validation
A practical developer reference designed to solve real implementation and production problems around sms api webhook security: signatures, authentication, replay protection and validation.
Why webhook security matters
A webhook endpoint is an internet-facing ingestion point. Anyone who can reach it may attempt to submit fake delivery events unless the receiver verifies authenticity.
Signature verification
Use a cryptographic signature over the exact request body and a shared secret or asymmetric verification mechanism supported by the platform. Verify the signature before parsing business fields.
Raw body requirement
Frameworks that automatically parse JSON can change the byte representation. Signature verification should use the exact raw body supplied by the sender.
Timestamp and replay protection
Include a timestamp or nonce in the signed material and reject events outside a defined tolerance. Store event IDs so an attacker cannot replay a valid event repeatedly.
Credential isolation
Webhook secrets should be stored separately from ordinary application configuration and should not be embedded in source code.
Secret rotation
Support overlapping old and new secrets during rotation so customers can change credentials without downtime.
IP allowlisting
IP filtering can be a useful additional layer but should not replace cryptographic authentication because network addresses can change.
TLS
Use HTTPS and valid certificates. Do not send authenticated webhook traffic over plain HTTP.
Tenant isolation
A valid signature must not automatically authorize access to unrelated tenant resources. Bind the webhook endpoint and credentials to the correct tenant.
Logging
Log verification result, event ID, timestamp and request metadata while avoiding message content and secrets.
Testing
Test altered bodies, invalid signatures, stale timestamps, duplicate event IDs and rotated secrets.
Reference checklist
Authenticate → verify raw body → validate timestamp → check event ID → validate schema → authorize tenant → enqueue → acknowledge.
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.
Canonical signing scheme
Choose one documented signing format and apply it consistently. A common pattern is to send a timestamp, an event ID and a signature derived from the timestamp plus the exact raw request body. The receiver computes the signature independently and compares it using a constant-time comparison. The exact algorithm should be documented rather than inferred from examples.
Why raw bytes matter
JSON objects can be represented in different textual forms while containing the same data. Whitespace, key order or escaping can change the byte sequence. If the signature is calculated over raw bytes, the receiver must verify those bytes before a framework transforms the request into an object. This is a frequent integration failure in webhook implementations.
Replay prevention
Signature validity alone does not prove freshness. An attacker who captures a valid request could resend it later. Include a signed timestamp and reject events outside the allowed tolerance. Also persist the event ID after successful authentication. The combination of freshness and event-ID deduplication provides much stronger replay protection.
Secret rotation
A practical rotation process allows a current and next secret to overlap temporarily. The sender can sign with the new secret while the receiver continues accepting the old secret during the migration window. Once all consumers are updated, revoke the old secret. Document the process because emergency secret rotation is difficult if customers have to discover the procedure during an incident.
Layered controls
HTTPS, IP restrictions, signatures, timestamp validation and tenant authorization serve different purposes. Do not treat one layer as a replacement for all others. IP addresses can change, TLS protects transport but does not prove application identity, and a valid signature does not authorize access to unrelated tenant records.
Security testing
Test a modified body, modified timestamp, reused event ID, wrong secret, rotated secret, missing signature, malformed signature and delayed delivery. Verify that failed requests do not reach business processing. Log enough evidence to diagnose authentication problems without logging the secret or unnecessary message content.
Signature verification example flow
The receiver reads the raw request body, extracts the signature and timestamp headers, constructs the documented signing string and computes the expected signature using its configured secret. It then performs a constant-time comparison. Only after successful verification should the JSON be parsed and the event ID processed. This order matters because parsing or normalization before verification can invalidate the signature.
Secret storage
Use a dedicated secret store where possible and restrict access to the webhook-processing component. Secrets should never appear in source repositories, configuration committed to version control or application logs. If multiple environments exist, use separate secrets so a development compromise cannot authenticate against production.
Clock tolerance
Timestamp validation requires a reasonable clock tolerance. Systems with inaccurate clocks can reject valid events, so production servers should synchronize time. The tolerance should be documented and measured from the signed timestamp rather than from an untrusted client field.
Compromise response
If a secret is suspected to be exposed, revoke it and issue a replacement. Preserve security audit records showing the rotation. If the platform supports two active secrets, use the overlap window to update customers without dropping valid events.
Signature test vectors
Publish a canonical example containing timestamp, event ID, body and expected signature for each supported signing algorithm. Developers can use it as a unit-test fixture. Test vectors eliminate ambiguity about separators, encoding, hexadecimal versus base64 representation and timestamp formatting.
Rotation without downtime
The receiver should be able to accept both current and previous secrets during a defined overlap. The sender should use one active signing secret at a time. After confirmation that customers have migrated, revoke the previous secret. This should be documented as a repeatable operational procedure.
Threat model
Protect against forged events, replay, secret exposure and cross-tenant misuse. Cryptographic verification addresses authenticity, while event authorization and tenant binding address whether the authenticated event is allowed to affect a particular resource.
Canonicalization mistakes
Many signature integrations fail because the sender and receiver canonicalize data differently. Document exactly which headers, separators, timestamp format and body bytes are signed. If the platform supports multiple algorithms, provide separate test vectors and explicit algorithm identifiers.
Key identifiers
A secret should have a public identifier or key ID that can be logged safely. The key ID tells the receiver which secret to try without exposing the secret. During rotation, the key ID also makes troubleshooting much easier.
Security review checklist
Review signature verification, constant-time comparison, timestamp tolerance, event-ID storage, secret access, TLS, tenant binding, logging and rotation before production. Security should be part of webhook onboarding rather than a later enhancement.
Operational isolation
Webhook authentication should occur before tenant lookup based on event fields supplied by the sender. After signature verification, use the authenticated webhook configuration to determine which tenant owns the event. Do not trust a tenant ID in the payload as the source of authorization.
Incident evidence
During a security incident, operators should be able to identify the webhook key ID, event ID, verification result and source metadata without exposing the secret or message body. Retain only what is needed for investigation and apply appropriate retention controls.
Secure onboarding
Webhook setup should require HTTPS, a verified destination and a generated secret before production events are enabled. A customer should be able to rotate the secret and test a signed event from the administration interface. Avoid making customers copy secrets into multiple places unnecessarily.
Final security principle
Webhook security is strongest when cryptographic authenticity, replay protection, tenant authorization, TLS and operational auditing work together. No single control should be treated as sufficient.
Production implementation detail
Before enabling a webhook in production, perform a complete verification test from signature creation through business-queue insertion. Confirm that an altered body is rejected, an old timestamp is rejected, a duplicate event is acknowledged without duplicate processing and a valid rotated secret is accepted. Record the verification result in the integration test evidence. This gives enterprise customers a repeatable security checklist rather than a vague recommendation to 'secure webhooks'.