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.