Glossary
HMAC-SHA256
HMAC-SHA256 is a keyed hash that proves a webhook came from someone holding the shared secret. OneLifeVibe signs each delivery with it.
Updated November 12, 2026
- Standard
- RFC 2104
- Also called
hash-based message authentication code
At OneLifeVibe
- Each OneLifeVibe delivery carries webhook-id, webhook-timestamp (Unix seconds) and webhook-signature: v1= followed by the hex HMAC-SHA256 of "{timestamp}.{raw body}" with the endpoint secret. The secret is returned once, when the subscription is created.
- webhook-signature is v1= followed by the lowercase hex HMAC-SHA256 of "{webhook-timestamp}.{raw body}", keyed with the endpoint secret as UTF-8 text. The secret is returned once, when the subscription is created.
Related terms
What it means
HMAC-SHA256 is a hash-based message authentication code built on SHA-256, the construction standardized in RFC 2104. You give it two inputs: a secret key and the exact bytes of a message. It returns a fixed-size tag, usually written as lowercase hex.
The key is the point. A plain SHA-256 digest shows that bytes changed, but anyone can compute it. HMAC mixes in a shared secret, so only someone who holds that secret can produce a tag that matches. That is what lets a receiver treat a valid tag as proof that the sender knows the secret and the message arrived unchanged. It authenticates; it does not encrypt. The payload stays readable.
How it works
Both sides start with the same secret. The sender computes the tag over the bytes it will send, then sends the message and the tag. The receiver computes the same tag over the bytes it received, using the same secret, and compares the two.
Exact bytes matter. If you parse a JSON body and re-serialize it, key order, spacing and number formatting can change, so the tag will not match. Verify against the raw request body before any parsing. Compare the full tag in constant time rather than with an early-exit string comparison.
Many schemes sign more than the body. A timestamp can be included in the signed string, which ties the tag to a moment and gives the receiver a way to reject old deliveries. Replay windows and header names are choices made by the API you integrate with, so read its documentation.
How OneLifeVibe uses it
Every OneLifeVibe delivery carries three headers: webhook-id, webhook-timestamp in Unix seconds, and webhook-signature. The signature value is v1= followed by the lowercase hex HMAC-SHA256 of the string {webhook-timestamp}.{raw body}. The key is the endpoint secret, treated as UTF-8 text. The secret is returned once, when the subscription is created.
To verify, take the raw body exactly as received. Build the signed string by joining the timestamp and the body with a dot. Compute HMAC-SHA256 with the endpoint secret, convert to lowercase hex, and compare that with the part of webhook-signature after v1=. If it matches, the request came from someone who holds the secret and the body was not altered. If it does not, reject the delivery and do not process the payload. Check that you stored the endpoint secret from subscription creation, that you used the raw body, and that the timestamp value is the one from the header.
Common mistakes
Signing the parsed payload instead of the raw body is the most common failure. Frameworks that parse JSON before your handler sees it can hand you an object, not the original bytes. Keep a raw-body path for webhook routes.
Another is including or excluding the wrong pieces. The v1= prefix is not part of the HMAC input. The dot between timestamp and body is. Uppercase hex will not compare equal to the lowercase hex in the header unless you normalize both sides.
Do not treat HMAC as encryption, and do not skip the comparison because the payload looks plausible. Also check freshness if your system needs replay protection. OneLifeVibe sends webhook-timestamp; the decision about how old a delivery may be belongs in your handler.
Questions
How do I verify a OneLifeVibe webhook signature?
Read the raw body, take webhook-timestamp from the headers, and compute HMAC-SHA256 over the timestamp, a dot, and the raw body using the endpoint secret as UTF-8 text. Compare the lowercase hex result to the value after v1= in webhook-signature. Reject the delivery if they differ.
What is signed in a OneLifeVibe webhook, and where does the secret come from?
The signed string is {webhook-timestamp}.{raw body}, keyed with the endpoint secret. The secret is returned once, when the subscription is created. Store it then, because the signature cannot be checked without it.
See it working. The OneLifeVibe connector and Platform API put these pieces together.
Written from the OneLifeVibe tool registry and platform configuration, and checked automatically before publishing. Something wrong? Tell us.