Glossary
UTF-8
UTF-8 is a text encoding where one character can take several bytes. OneLifeVibe treats the endpoint secret as UTF-8 text when signing webhooks.
Updated November 15, 2026
- Standard
- RFC 3629 (UTF-8)
- Also called
UTF8
At OneLifeVibe
- 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.
What it means
UTF-8 is a way to turn text into bytes and back. It is defined in RFC 3629, and you will also see it written UTF8. A character can take one byte or several, so a string's length in characters and its length in bytes are different numbers. The first 128 code points map to single bytes, which keeps UTF-8 compatible with ASCII for plain English text.
Encoding is not a font or a language. It is a rule about byte sequences. When two systems agree on UTF-8, an accented letter or a symbol survives the trip as the same bytes. The same character in another encoding may produce different bytes, which is why the encoding matters wherever text becomes bytes.
How it works
An encoder reads a character and writes a sequence of one to four bytes. A decoder reads the leading bits of each byte to work out how many bytes belong to the next character. That design means you cannot safely slice a UTF-8 string at an arbitrary byte offset and expect valid text. If a decoder meets an invalid sequence, it can reject the input or replace it, depending on the decoder.
HMAC-SHA256 works on bytes, not characters. To use a text secret as an HMAC key, both sides must turn that text into the same bytes. A secret read as UTF-8 on one side and as something else on the other produces a different key, so the signatures will not match. The encoding rule is part of the signing contract, not a detail you can leave to chance.
How OneLifeVibe uses it
OneLifeVibe uses the endpoint secret as UTF-8 text when signing. The webhook-signature value is v1= followed by the lowercase hex HMAC-SHA256 of "{webhook-timestamp}.{raw body}", keyed with that secret. The secret is returned once, when the subscription is created, so store it at that point.
To verify a delivery, build the signed string from the webhook-timestamp value, a literal period, and the raw body exactly as received. Compute HMAC-SHA256 with the endpoint secret as UTF-8 text, turn the result into lowercase hex, and compare it with the part of webhook-signature after v1=. If the values differ, check the raw body bytes and the secret encoding first. Parsing the body and writing it back out can change whitespace or field order, and then your hash covers different bytes.
Common mistakes
The most common mistake is hashing a parsed body instead of the raw body. Parsing and rebuilding can change whitespace or field order, so the byte string you hash is no longer the one that was signed. Read the bytes as they arrived.
Another mistake is treating the secret as bytes from somewhere else, such as a hex decode, when the signing rule says UTF-8 text. Check the hex case and the v1= prefix too: the signature is v1= followed by lowercase hex, not uppercase and not the digest alone. Store the secret when the subscription is created, since that is the point when it is returned.
Questions
Does UTF-8 change how I compute the OneLifeVibe webhook signature?
It changes the key bytes. OneLifeVibe keys HMAC-SHA256 with the endpoint secret as UTF-8 text. The message is the webhook-timestamp, a literal period, and the raw body.
Should I hash the raw body or a parsed body?
Hash the raw body exactly as received. The signed string is {webhook-timestamp}.{raw body}, so parsing and rebuilding can change bytes and break the match. Check for the v1= prefix and lowercase hex when you compare.
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.