What Is HMAC Used For? Why APIs Need Signed Requests

A plain hash and an HMAC solve different problems

A plain hash function, like SHA256 on its own, takes any input and produces a fixed length digest. Change one character in the input and the digest changes completely. That property makes plain hashes great for checking that a file downloaded correctly, or that two copies of a document are identical. You can compute a hash with our hash generator and compare it against a published checksum in seconds.

The problem is that a plain hash carries no secret. Anyone, including an attacker sitting between a client and a server, can take a payload, run it through SHA256, and produce the exact same digest you would. So if a server only checks “does the hash match,” it has confirmed the payload was not corrupted by a network glitch, but it has confirmed nothing about who sent it. An attacker who intercepts a request, changes the amount field in a payment, and recomputes the hash will produce a digest that still matches the tampered body perfectly.

Where the secret key changes everything

HMAC fixes this by mixing a shared secret key into the hashing process itself. Instead of hashing just the message, HMAC combines the key and the message through two nested hash operations, roughly hash(key XOR opad, hash(key XOR ipad, message)) using whichever underlying hash function you choose, commonly SHA256. The output, called a signature or a tag, depends on both the message and the key. Change either one and the signature is different.

This is precisely what is HMAC used for in practice: only someone who knows the secret key can produce a signature that the receiving server will accept. An attacker who intercepts a request can still read it, and can still change it, but cannot forge a valid signature for the altered version without the key. The server recomputes the expected signature using its own copy of the secret and compares it against the one attached to the request. If they match, the server trusts both that the sender knows the secret and that the payload was not modified after signing.

A concrete example: verifying a webhook from a payment provider

Most payment processors send webhooks to notify your server about events like a completed charge or a refund. Because these webhooks trigger real actions, such as marking an order paid or releasing a shipment, you cannot just trust whatever hits your endpoint. Anyone who guesses your webhook URL could send a fake “payment succeeded” event otherwise.

To prevent that, the provider signs each webhook body with HMAC using a secret only your account and the provider know. The request typically arrives with a header like this:

X_SIGNATURE: t=1700000000, v1=5257a869e7…

Your server takes the raw request body, runs it through HMAC SHA256 with your webhook secret, and checks the result against the v1 value in the header. If they match, the event is genuine and unaltered, so you process it. If they do not match, you reject the request outright, no matter how legitimate the payload looks. This single check is what stops a forged “refund issued” event from draining your ledger.

Constant time comparison matters too

One detail teams get wrong is comparing signatures with a normal string equality check. A naive comparison can exit early on the first mismatched byte, and the tiny timing difference between failing at byte one versus byte thirty can, in theory, leak information to an attacker probing many requests. Proper implementations use a constant time comparison function so every check takes the same amount of time regardless of where the mismatch occurs. Most standard libraries ship one specifically for this purpose, so use it rather than writing your own comparison loop.

HMAC compared to other things that look similar

It helps to separate HMAC from a few adjacent concepts. A JSON Web Token, which you can inspect with our JWT decoder, often uses HMAC internally as one of its signing algorithms, specifically HS256. But a JWT is a container format for claims, while HMAC is the signing mechanism that protects the token from tampering. You can have HMAC without JWT, such as signing a webhook body directly, and JWT without HMAC, if the token uses RSA or ECDSA signatures instead.

Base64 encoding is another thing people sometimes confuse with security. Encoding a signature with our base64 encoder just changes how bytes are represented as text so they survive transport in a URL or header. It adds no secrecy and no integrity guarantee on its own. HMAC provides the actual protection; base64 is just packaging.

Password hashing is a separate case again. When you store user passwords, you want a slow, salted hash designed to resist brute force, not HMAC. Our password strength checker is useful for the input side of that problem, but the storage mechanism itself is a different topic from request signing entirely.

Why not just encrypt the request instead

Encryption and HMAC solve different problems too. Encryption keeps content secret from anyone without the decryption key. HMAC does not hide anything, since the message can travel in plain text alongside its signature. What HMAC guarantees is authenticity and integrity: this message came from someone with the key, and it has not changed since they signed it. Many systems run over HTTPS, which already provides transport encryption, and then add HMAC on top so the application layer itself can verify sender identity even if something further up the chain terminates or re originates the connection. The two mechanisms are complementary, not substitutes for each other.

The formal definition of HMAC comes from RFC 2104, published by the IETF, which specifies exactly how the key and message get combined with the underlying hash function. If you want the precise construction rather than a summary, that document is the primary source.