Glossary · Triggers & webhooks
HMAC signature
Also called: HMAC-SHA256, webhook signature, signed webhook
An HMAC signature is a hash of a message computed with a secret key that only the sender and receiver know, sent alongside the message so the receiver can prove it came from the sender and wasn't altered.
HMAC stands for hash-based message authentication code. The sender takes the exact bytes of the request body, runs them through a hash function (almost always SHA-256) together with a shared secret, and puts the result in a header. The receiver does the same calculation with its copy of the secret. If the two results match, the body is authentic and intact; if a single byte changed, they won't.
Verifying one, step by step
- Read the raw request body, before any JSON parsing. Re-serializing parsed JSON changes whitespace and key order, and the signature stops matching.
- Compute
HMAC-SHA256(secret, rawBody)and hex-encode it. - Compare it with the header value (often prefixed, like
sha256=…) using a constant-time comparison, so response timing doesn't leak how much of the signature was right. - Reject with
401or403on mismatch, and don't start any work.
Replay protection
A valid signed request can be captured and resent. Senders defend against that by signing a timestamp along with the body (timestamp.body) and receivers reject anything older than a few minutes. Stripe and Slack both use variants of this.
A shared secret header is simpler but weaker: anyone who sees one request can reuse the secret forever, and it says nothing about whether the body was changed in transit. HMAC proves both.
In Fluxo Flow
A Webhook trigger in Signature mode expects x-fluxo-signature: sha256=<hex>, the HMAC-SHA256 of the raw body made with the trigger's secret. If the sender adds x-fluxo-timestamp, the signature must cover timestamp.body and the timestamp must be within five minutes; you can make the timestamp mandatory. Comparisons are constant-time. Outbound, every API webhook delivery carries a Fluxo-Signature header (HMAC-SHA256 of the timestamp and body) with verification code for Node.js and Python in the docs.
Read next
Related terms
- WebhookA webhook is an HTTP request that one system sends to a URL you give it, automatically, the moment an event happens, so the receiver doesn't have to keep asking.
- Scoped API keyA scoped API key is an API credential limited to specific permissions (scopes), often with an expiry date, so that a leaked or misused key can only do what it was explicitly allowed to do.
- Idempotency keyAn idempotency key is a unique value a client sends with a request so that, if the same request is retried, the server recognizes it and returns the original result instead of doing the work a second time.
- Human in the loop (HITL)Human in the loop (HITL) is a design in which an automated process pauses at chosen points for a person to review, correct, approve or reject its output before it continues.
- Exponential backoffExponential backoff is a retry strategy in which the wait before each new attempt grows exponentially (for example 1, 2, 4, 8 seconds), usually with random jitter, up to a maximum number of attempts or delay.