Skip to content
← All articles
6 min read

Webhook security signature verification: architecture and defense

Webhook security signature verification is the foundation of secure event-driven integrations between independent systems. Without verifying sender identity and payload integrity, public webhook endpoints remain exposed to request forgery, replay attacks, and unauthorized state changes. Here is how to architect webhook verification correctly from incoming request to background processing.

Why public endpoints require cryptographic authentication

Webhooks deliver asynchronous event notifications over open HTTP or HTTPS channels. Unlike internal service calls protected by private networks or mutual TLS, a webhook endpoint must accept incoming POST traffic from the public internet. Relying merely on an obscure URL path or an IP address whitelist creates fragility, because network paths can be routed through proxies, and static endpoints can be probed or flooded.

Cryptographic message signing using Hash-based Message Authentication Codes (HMAC) solves this problem at the application layer. The sending service computes a cryptographic hash of the raw payload using a shared secret and includes that signature in a request header. The receiver computes the identical hash and verifies that the payload has not been tampered with and genuinely originated from the service holding that secret.

Verifying signatures using the raw request body

A common failure in signature verification stems from parsing the payload before hashing it. JSON deserializers frequently alter key ordering, reformat whitespace, or normalize floating-point representations. Because cryptographic hashes depend on every single byte, any variation between the sent payload and the checked payload causes verification to fail.

The receiving application must capture the exact raw byte stream from the incoming HTTP request body before JSON or form parsers run. The HMAC digest is computed directly over these raw bytes using the shared signing secret, and only after validation succeeds should the payload be parsed into internal data structures.

Preventing timing attacks with constant-time comparison

Standard string equality operators return false as soon as the first non-matching byte is encountered. This behavior allows attackers to measure minuscule differences in response latency to guess signature bytes incrementally, creating a timing attack vulnerability.

Verification logic must compare the received signature and the calculated signature using a constant-time comparison function, such as crypto.timingSafeEqual in Node.js or hmac.compare_digest in Python. These functions evaluate every byte regardless of where differences occur, eliminating timing side channels entirely.

Replay attack protection using timestamps

Even if a signature is valid, an eavesdropper or intermediate network actor who intercepts the request can resend that exact request repeatedly to trigger duplicated operations. Without replay protection, a valid payment confirmation or status update could be processed multiple times.

The sender should include an explicit timestamp in a dedicated header, and that timestamp must be incorporated into the signed payload string. The receiver enforces defense through two layers:

  • Timestamp freshness checks: reject any request whose timestamp falls outside an acceptable drift window relative to the receiver clock.
  • Idempotency tracking: store unique event identifiers or request signatures in a cache to reject duplicate deliveries that arrive within the valid window.

Managing shared secrets and zero-downtime rotation

Shared secrets must be generated using cryptographically secure random generators and stored strictly in environment variables or key management vaults, never in application source code. When credentials need to be rotated due to schedule or compromise, changing a secret instantaneously across both sender and receiver is impossible without dropping incoming events.

Zero-downtime secret rotation requires dual-key support during transitional periods. The receiver maintains both the current active secret and the retiring previous secret. Incoming requests are verified first against the primary key; if validation fails, the system attempts verification against the secondary key before rejecting the request.

Fast acknowledgment and background queue processing

Webhook providers enforce strict HTTP request timeout limits. If your webhook handler runs heavy database transactions, synchronizes external APIs, or generates files synchronously within the HTTP lifecycle, external providers will assume the request timed out and initiate aggressive retries.

The HTTP endpoint should perform signature verification, validate basic headers, acknowledge receipt with an immediate HTTP 200 or 202 status code, and push the verified payload onto an asynchronous job queue for decoupled background execution. For Telegram bots, the choice between webhooks and getUpdates is covered in webhook vs long polling.

Questions

FAQ

Didn't find an answer — ask on the call or in Telegram.

Why is an IP address whitelist not enough on its own?

IP whitelists provide network filtering, but many cloud providers send webhooks through dynamic IP ranges or shared egress gateways. Furthermore, IP checks do not verify payload integrity. Cryptographic signatures ensure the payload was not modified in transit and prove knowledge of the shared secret regardless of routing.

What should the receiver return when signature verification fails?

When a signature fails verification or a timestamp is expired, the endpoint should return a 400 or 401 HTTP status code with a generic error message. Avoid revealing details about secret configuration or internal comparison logic to prevent information leaks.

How should signature formats be structured in headers?

Industry implementations typically send headers containing both the algorithm identifier and the signature value, often accompanied by the timestamp. A common pattern passes the timestamp and signature together, allowing the receiver to reconstruct the signed string exactly as the sender assembled it.

Related service

CRM, ERP and API integrations built for your workflows

When teams copy data between systems by hand, delays and mistakes become part of the process. We automate the exchange and make its status visible to the people running it.

Learn about the service
Other articles
Contact

Shall we discuss your task?

Thirty minutes on a call — and you understand the architecture, timeline and engagement format. No obligations.

Or message us on Telegram →Follow our Telegram channel →

Enter your Telegram or email so we can reply.

We reply within 15 minutes.