Transactional SMS API Webhook Security: HMAC Signatures, IP Controls, Replay Protection and Verification

Webhook threat model

A webhook is an inbound API to the customer's application. An attacker who can forge a delivery event might falsely mark a transaction complete, trigger customer notifications or manipulate downstream business workflows.

HMAC signatures

The provider can sign a canonical representation of the webhook using a shared secret. The receiver computes the expected signature and compares it using a constant-time mechanism.

Signed body integrity

The signature should cover the exact body bytes or a precisely defined canonical representation. Parsing JSON and then reserializing it before verification can create mismatches if serialization rules differ.

Timestamp validation

A timestamp included in the signature limits the useful lifetime of a captured event. Reject requests outside the allowed clock-skew window after considering reasonable network delay.

Replay protection

Store recently accepted event IDs or nonces for at least the replay window. If the same signed event arrives again, the application can safely acknowledge it without executing the business action twice.

IP controls

Allowlisting provider IP ranges can add a network-level layer, but IP addresses should not replace cryptographic authentication because ranges can change and traffic may traverse proxies.

Secret rotation

Webhook secrets should support controlled rotation. During migration, the receiver can accept the current and previous secret for a limited period, then retire the old one.

TLS

Webhook endpoints should use valid certificates and reject insecure protocols. TLS protects the connection, while signatures protect message authenticity at the application layer.

Safe verification errors

Return generic authentication failures to callers while recording safe diagnostic metadata internally. Never expose the expected signature, secret or canonical signing string in a public error response.

Framework integration

Many web frameworks parse the request body before application code sees it. Signature verification may require access to the raw body, so implementation guidance must account for middleware ordering.

Testing

Test modified bodies, missing signatures, invalid signatures, expired timestamps, replayed event IDs, secret rotation and proxy behaviour.

Implementation checklist

Document signing algorithm, canonical input, timestamp window, event ID retention, secret rotation, TLS requirements, IP controls and framework-specific raw-body handling.

Canonical signing specification

A robust webhook signing protocol should define exactly what is signed. One practical approach is to sign a version, timestamp, event ID and hash of the raw request body. The receiver can reconstruct the same signing input without depending on JSON property ordering.

The documentation should include fixed examples so independent implementations can verify compatibility.

Raw-body handling

Framework middleware can parse JSON and discard the original byte representation. If the signature covers raw bytes, verification must occur before body transformation or the framework must expose the original payload.

This is a common source of integration failures and should be highlighted in SDK documentation.

Replay cache design

The replay store does not need to retain complete webhook bodies. A short-lived record containing event ID, tenant, acceptance time and signature version can be sufficient to prevent repeated execution during the replay window.

IP allowlist lifecycle

If IP restrictions are used, provider address ranges must have an update process. A static allowlist that is never reviewed can unexpectedly block legitimate traffic after provider infrastructure changes.

Cryptographic verification should remain the primary trust mechanism.

Secret compromise

If a webhook secret is exposed, rotate it and determine whether malicious requests could have been accepted. Review recent event IDs, endpoint logs and downstream actions for suspicious activity. The secret should never be included in support tickets or debugging screenshots.

Developer reference rule

Webhook security should use layered controls: TLS for transport, signatures for authenticity and replay protection for event freshness. Network controls can supplement these mechanisms but should not replace them.

Signature versioning

Include a signature version in the header or event metadata so cryptographic protocol changes can be introduced without breaking existing integrations. Support the previous version only for a defined migration period and communicate retirement dates clearly.

Webhook secret scope

A separate secret per tenant or endpoint provides stronger isolation than one platform-wide secret. If one customer endpoint is compromised, rotating that customer's secret does not invalidate every integration.

Replay-window selection

The replay window should balance network delay against attack exposure. A very long window increases the period in which a captured request may be reused; a very short window can reject legitimate events when customer clocks or network conditions are unusual.

Signature verification sequence

Verify TLS connection, read the raw body, validate required signature fields, check timestamp freshness, compute the expected signature, compare safely and then check event-ID replay state. Only after these checks should business processing begin.

Framework example

Some frameworks expose the parsed JSON object but not the original request bytes. In that case, configure raw-body capture before JSON parsing or use an official SDK that preserves the required representation.

Practical scenario

A webhook is captured and resent several minutes later. The signature itself is valid, but the timestamp is outside the allowed window, so the receiver rejects the replay. If the original event is resent normally within the retry window, its event ID can be recognized as already processed and safely acknowledged.

Failure scenario

A customer accidentally deploys an endpoint that modifies the JSON body before signature verification. Every request fails even though the provider signature is correct. The fix is to verify against the original body bytes before parsing or transforming the payload.

Operational checklist

Verify raw-body availability, signature version, timestamp window, replay cache, secret rotation, TLS, IP policy, safe errors and test vectors across supported frameworks.

Developer takeaway

Webhook authentication is only reliable when the receiver can independently reproduce the signing input. Precise protocol documentation is therefore part of the security design.

Design review

Review the signing protocol whenever SDKs, gateways or framework middleware changes. Security can be weakened by an apparently harmless body-parsing change.

Reference note

Never solve signature mismatches by disabling verification. Find the canonicalization or raw-body discrepancy and fix the integration.

Final standard

Webhook authenticity must be independently verifiable by every supported customer implementation.

Implementation example

A webhook receiver validates the raw body against the HMAC signature, checks the timestamp and event ID, then stores the event. Only after those checks does it publish the business event internally. This prevents forged callbacks from entering downstream workflows.

Testing standard

Test byte-level body modification, header modification, timestamp manipulation, replay, secret rotation, missing signatures and invalid signature lengths. Security tests should verify that no secret or expected signature appears in logs.

Final checklist

Confirm cryptographic verification happens before business processing and before a public success response is returned.

Capacity example

If thousands of callbacks arrive simultaneously, signature verification should remain lightweight enough to protect the callback gateway. Expensive business processing belongs after verification and durable acceptance, not in the initial authentication path.

Support guidance

When a signature fails, verify secret version, raw body handling, timestamp, canonicalization and clock skew before rotating credentials. Unnecessary rotation can create a second problem when the real issue is framework configuration.

Reference rule

Verify first, process second, acknowledge only after safe acceptance.

Production readiness

Before enabling a high-volume webhook integration, perform a controlled endpoint outage test. Confirm that the platform continues accepting provider events, retries with bounded backoff, isolates the affected tenant and resumes delivery after recovery. Confirm that duplicate events remain harmless.

Documentation requirement

Publish a webhook integration page covering event schemas, signature verification, response codes, retries, idempotency and versioning. Include complete examples and explain what the customer should store as the event's unique identity.

Long-term maintenance

Review webhook schemas and delivery guarantees whenever a new event type is added. Avoid changing the meaning of existing fields because customers may have persisted them for years.

Final production rule

Do not accept a webhook event as trusted until its signature, freshness and replay controls have passed.

Reference summary

The safest webhook integrations make verification, idempotency and retry handling part of the normal application architecture rather than exceptional security code.