HMAC

HMAC (hash-based message authentication code) combines a secret key with a message through a hash function such as SHA-256. The sender computes it and sends it alongside the message; the receiver computes it again with the same secret. If they match, the message is authentic and unchanged.

Using HMAC correctly:

• Sign the raw bytes. Parsing and re-serialising JSON before checking changes the bytes and breaks the signature.
• Compare in constant time, so the check can't leak the signature byte by byte.
• Include a timestamp in what's signed, and reject old messages, so a captured request can't be replayed later.
• Protect the secret like a password. Anyone who has it can forge messages.

The last point is HMAC's weakness: the receiver holds the same secret as the sender. Public-key signatures such as Ed25519 avoid it.

On Valtu

Every webhook carries X-Valtu-Signature, an HMAC-SHA256 over <timestamp>.<raw body> with the endpoint's secret, shown once when you add the endpoint. Each delivery is also signed with Ed25519, which we recommend because there's nothing secret to store.