Verifying a Thomas webhook signature
Every webhook Thomas delivers carries a Thomas-Signature header. This page is everything
you need to verify one: what is signed, how the header reads, how to check it, and fixed test
vectors to run your implementation against before you trust it.
You do not need access to Thomas source to follow this. Every value below is reproducible
with openssl or python3.
http
Thomas-Signature: t=1757930000,v1=9b4d2f82c89f39c7a2780f4363b9cd3f97d6e9fca8696a73ef4555e6af499a51
t is the attempt timestamp, in Unix seconds. It is never milliseconds and never
fractional. A retry is a new attempt: it keeps its event id but gets a fresh t and fresh
signatures.v1 is one HMAC-SHA256 signature, rendered as exactly 64 lowercase hex digits.- There may be more than one
v1. See section 5.
The grammar is strict, and here is exactly how
Thomas emits, and you should require:
- Exactly one
Thomas-Signature header per request. If a request carries two, reject
it — do not merge them and do not pick one. The header name is case-insensitive on the
wire, as HTTP requires; the parameter names inside it are not. - No whitespace anywhere in the value. Parameters are separated by a bare
, and each
is name=value with a bare =. Thomas never emits a space, and you should not trim one. t is a canonical digit run: no sign, no leading zeros, no decimal point, no
exponent. Validate it against the literal characters, not by parsing it as a number —
Number(' 12 '), Number('1e3') and Number('0x10') all succeed and accept a header no
emitter produces. The literal digit run as received is what was signed, so build the
signed string from those characters, never from a re-formatted number.
Its value is from 0 through 999999999999; 1000000000000 and above have
millisecond magnitude and are rejected. This also bounds the digit run before conversion.v1 is exactly 64 lowercase hex digits. An uppercase, short or long value is
malformed; reject the request rather than skipping that value.- A parameter with no
= is malformed — reject the request. It is not a future
extension. - An unrecognised parameter NAME is ignored. That is the one thing you must be lenient
about: a future scheme arrives as a new name (
v2=) beside v1, and a verifier that
rejects what it does not recognise breaks on the day we add one.
2. What is signed
The signed string is the timestamp, a single ., and the raw request body:
text
<t>.<raw request body>
Concatenated as bytes, UTF-8, with nothing appended, prefixed, trimmed or normalised.
Use the raw body your HTTP framework received, before any JSON parsing. If you parse
the body and re-serialise it, your bytes will differ from ours — key order, whitespace and
\uXXXX escaping all survive on the wire and all change the signature. The
key-order-variant and unicode-escape vectors in section 7 exist so
that a re-serialising verifier fails your own test suite rather than production.
Note that the body may itself contain . characters. That is not ambiguous: the separator is
the first . after the timestamp, and you never need to split the signed string — you build
it, you do not parse it.
3. The key
The HMAC key is the signing secret exactly as Thomas issued it: the 43-character
base64url string returned once, when the subscription was created or its secret rotated.
Use its UTF-8 bytes directly.
Do not base64url-decode it first. The string is the key.
4. How to verify a request
- Read the single
Thomas-Signature header and split it on , into name=value
parameters, applying the grammar rules in section 1. Reject on anything
malformed rather than skipping it. - Take
t and reject the request if it is more than 300 seconds away from your own
clock, in either direction. This is the replay window; it is five minutes, and Thomas will
not widen it. - Build
<t>.<raw request body> from the literal timestamp characters you just read and the raw body
bytes. - Compute
HMAC-SHA256(key = your signing secret, message = that byte string) and render it
as lowercase hex. - Compare your value against every
v1 in the header, using a constant-time
comparison (hmac.compare_digest, crypto.timingSafeEqual, MessageDigest.isEqual).
Accept if any one matches. A plain == on a signature leaks timing information. - Reject if none matches.
Steps 2 and 5 are both required. A signature check without the timestamp window accepts an
indefinite replay of a captured request, and a match against only the first v1 fails during
a rotation.
5. Rotation
When you rotate your signing secret, Thomas emits one v1 per secret version that is
currently valid, with the subscription's active version first:
http
Thomas-Signature: t=1757930000,v1=<signed with the new secret>,v1=<signed with the previous one>
- A routine rotation keeps the previous secret verifying for a bounded overlap of up to
24 hours, so in-flight deliveries keep verifying while you redeploy.
- A compromise rotation retires the previous secret immediately. It contributes no
v1
from that moment, and neither does any version whose overlap window has passed. - A subscription that is not mid-rotation emits exactly one
v1.
This is why step 5 says any v1. During the overlap you may hold either secret; check your
secret against every value and accept on the first match. The rotation-overlap vector in
section 7 is the one to test this against.
6. A runnable example
This reproduces the first test vector end to end. Paste it into a shell:
bash
printf '%s' '1757930000.{"id":"018f3a5c-7b21-8c4d-9e6f-0a1b2c3d4e5f","type":"assessment.completed","version":1,"occurredAt":"2025-09-15T09:53:12.000Z","tenantId":"4f9c1e2a-6d3b-4a15-9c8e-2b7d0f5a1c34","sequence":4,"data":{"assignmentId":"7c2e9a10-5f4b-4d83-b1a6-9e0c3d7f2b58","subjectId":"2a6f8c31-0b95-4e27-8d14-6c3a9f5b7e02","relationshipType":"employee","origin":"recruitment","resultId":"9d1b4e76-3c82-4f09-a5d7-1e8b6c40f293"}}' | openssl dgst -sha256 -hmac 'CVjxZry3CPr1awYKmRay7qHMl_2Jo2Pa4I0DV1L4V9g'text
SHA2-256(stdin)= 9b4d2f82c89f39c7a2780f4363b9cd3f97d6e9fca8696a73ef4555e6af499a51
The same check as a verifier, in Python:
python
import hashlib
import hmac
import re
import time
TOLERANCE_SECONDS = 300
_TIMESTAMP = re.compile(r"(?:0|[1-9][0-9]{0,11})")
_SIGNATURE = re.compile(r"^[0-9a-f]{64}$")
def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
"""raw_body is the request body as received - never a re-serialised object."""
if re.search(r"[\s\u001c-\u001f\u0085\ufeff]", signature_header):
return False
timestamps = []
candidates = []
for part in signature_header.split(","):
name, separator, value = part.partition("=")
if not name or not separator:
return False # malformed parameter: reject, never ignore
if name == "t":
if not _TIMESTAMP.fullmatch(value):
return False
timestamps.append(value)
elif name == "v1":
if not _SIGNATURE.fullmatch(value):
return False
candidates.append(value)
# any other NAME is a future extension: ignore it
if len(timestamps) != 1 or not candidates:
return False
if abs(time.time() - int(timestamps[0])) > TOLERANCE_SECONDS:
return False
signed_string = timestamps[0].encode("ascii") + b"." + raw_body
expected = hmac.new(secret.encode("utf-8"), signed_string, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(expected, candidate) for candidate in candidates)And in Node.js:
js
import { createHmac, timingSafeEqual } from 'node:crypto';
const TOLERANCE_SECONDS = 300;
const TIMESTAMP = /^(?:0|[1-9][0-9]{0,11})$/;
const SIGNATURE = /^[0-9a-f]{64}$/;
// rawBody is a Buffer of the bytes as received - do not JSON.parse and re-stringify.
export function verify(rawBody, signatureHeader, secret) {
if (/[\s\u001c-\u001f\u0085\ufeff]/.test(signatureHeader)) return false;
const timestamps = [];
const candidates = [];
for (const part of signatureHeader.split(',')) {
const separator = part.indexOf('=');
if (separator <= 0) return false; // malformed parameter: reject, never ignore
const name = part.slice(0, separator);
const value = part.slice(separator + 1);
if (name === 't') {
if (!TIMESTAMP.test(value)) return false;
timestamps.push(value);
} else if (name === 'v1') {
if (!SIGNATURE.test(value)) return false;
candidates.push(value);
}
// any other NAME is a future extension: ignore it
}
if (timestamps.length !== 1 || candidates.length === 0) return false;
if (Math.abs(Date.now() / 1000 - Number(timestamps[0])) > TOLERANCE_SECONDS) return false;
const signedString = Buffer.concat([Buffer.from(timestamps[0] + '.', 'utf8'), rawBody]);
const expected = createHmac('sha256', secret).update(signedString).digest('hex');
const expectedBytes = Buffer.from(expected, 'utf8');
return candidates.some(
(candidate) =>
candidate.length === expected.length &&
timingSafeEqual(expectedBytes, Buffer.from(candidate, 'utf8')),
);
}Both samples reject malformed input rather than raising, and neither skips a check when
something is wrong. That matters: a verifier that throws on a bad t turns a hostile request
into a 500 in your handler, and one that lets a non-numeric t through as NaN silently
skips the replay window entirely.
7. Test vectors
These are fixed. Run your verifier against all of them before you trust it — each one
pins a boundary a verifier gets wrong in a way production will not show you for months.
None of these expected values was produced by Thomas code: each was computed by openssl or
by CPython's hmac module from the literal signed string. So
agreeing with them is evidence, not a restatement of our own implementation.
The secrets below are fixture values. They belong to no subscription and are published on
purpose — a test vector you cannot reproduce is not a test vector.
Run fixed vectors with a controlled test clock
These timestamps are fixed in September 2025. Running the complete verifier against today's
clock correctly rejects them as expired. In an isolated test process, set the verification
clock to the vector's t before each call:
- Python: use
from unittest.mock import patch, then call verify(raw_body, header, secret)
inside with patch("time.time", return_value=t):. Encode the table's body as UTF-8 bytes. - JavaScript: save
const realNow = Date.now, set Date.now = () => t * 1000, call
verify(Buffer.from(rawBody, 'utf8'), header, secret), and restore Date.now = realNow
in a finally block.
Pass only the header value beginning t=, without the Thomas-Signature: label. Expect
true for each positive vector, including a separate call with each rotation secret.
Expect false for tampered-body, even with the clock set to its timestamp. Also test the
replay boundary: the valid vector passes with the clock exactly one TOLERANCE_SECONDS
window before or after t, and rejects one second beyond either boundary. Restore the
real clock after each test; live request
handlers must keep their live-clock replay check enabled.
Vectors that must VERIFY
envelope-assessment-completed
A complete assessment.completed delivery body.
| field | value |
|---|
t | 1757930000 |
| body | {"id":"018f3a5c-7b21-8c4d-9e6f-0a1b2c3d4e5f","type":"assessment.completed","version":1,"occurredAt":"2025-09-15T09:53:12.000Z","tenantId":"4f9c1e2a-6d3b-4a15-9c8e-2b7d0f5a1c34","sequence":4,"data":{"assignmentId":"7c2e9a10-5f4b-4d83-b1a6-9e0c3d7f2b58","subjectId":"2a6f8c31-0b95-4e27-8d14-6c3a9f5b7e02","relationshipType":"employee","origin":"recruitment","resultId":"9d1b4e76-3c82-4f09-a5d7-1e8b6c40f293"}} |
| secret | CVjxZry3CPr1awYKmRay7qHMl_2Jo2Pa4I0DV1L4V9g |
expected v1 | 9b4d2f82c89f39c7a2780f4363b9cd3f97d6e9fca8696a73ef4555e6af499a51 |
| header | Thomas-Signature: t=1757930000,v1=9b4d2f82c89f39c7a2780f4363b9cd3f97d6e9fca8696a73ef4555e6af499a51 |
empty-body
An empty body. The signed string is still <t> + . and nothing more.
| field | value |
|---|
t | 1757930001 |
| body | (empty) |
| secret | iJFGtcpX3zGOJHAhk0UIyGfvwb5YF2N4DMi2rRv8JjI |
expected v1 | defcec1f0a73bb8827fe17056d35669085b561077244cbe7bde2d5ffde2b998d |
| header | Thomas-Signature: t=1757930001,v1=defcec1f0a73bb8827fe17056d35669085b561077244cbe7bde2d5ffde2b998d |
multibyte-utf8
A literal U+00E9, which is two bytes. Hash bytes, not characters.
| field | value |
|---|
t | 1757930002 |
| body | {"note":"café"} |
| secret | zDfMZbEdWnpGy7E2aNpHsUrVpabuxt0_cBp0thhH8PI |
expected v1 | b2f42ef92c2f9342d801c84306c4365bd8d5c98d878a7c2bd7f3f53cc46c90d8 |
| header | Thomas-Signature: t=1757930002,v1=b2f42ef92c2f9342d801c84306c4365bd8d5c98d878a7c2bd7f3f53cc46c90d8 |
unicode-escape
The same JSON value as the row above, escaped. Same t, same secret, DIFFERENT signature.
| field | value |
|---|
t | 1757930002 |
| body | {"note":"caf\u00e9"} |
| secret | zDfMZbEdWnpGy7E2aNpHsUrVpabuxt0_cBp0thhH8PI |
expected v1 | bb23195a7d7bf4870818154ad7edf18da4135ee5364a129c17fef32ec9497fc4 |
| header | Thomas-Signature: t=1757930002,v1=bb23195a7d7bf4870818154ad7edf18da4135ee5364a129c17fef32ec9497fc4 |
separator-in-body
The body contains a . and a digit run. Only the FIRST . after the timestamp is the separator.
| field | value |
|---|
t | 1757930004 |
| body | {"note":"1757930000.not-a-timestamp"} |
| secret | 2YqeFjOhv1O-cbBuKdsUMRYSJ6saZec7um_SJfCbsIQ |
expected v1 | 8038ce209a8bb0b22f80568564b7beb0e6e0e7b92fdacb95fbdc4cff8beaec8b |
| header | Thomas-Signature: t=1757930004,v1=8038ce209a8bb0b22f80568564b7beb0e6e0e7b92fdacb95fbdc4cff8beaec8b |
key-order-variant
The same JSON value as the first row with its keys reordered. Same t, same secret, DIFFERENT signature.
| field | value |
|---|
t | 1757930000 |
| body | {"type":"assessment.completed","id":"018f3a5c-7b21-8c4d-9e6f-0a1b2c3d4e5f","version":1,"occurredAt":"2025-09-15T09:53:12.000Z","tenantId":"4f9c1e2a-6d3b-4a15-9c8e-2b7d0f5a1c34","sequence":4,"data":{"subjectId":"2a6f8c31-0b95-4e27-8d14-6c3a9f5b7e02","assignmentId":"7c2e9a10-5f4b-4d83-b1a6-9e0c3d7f2b58","relationshipType":"employee","origin":"recruitment","resultId":"9d1b4e76-3c82-4f09-a5d7-1e8b6c40f293"}} |
| secret | CVjxZry3CPr1awYKmRay7qHMl_2Jo2Pa4I0DV1L4V9g |
expected v1 | 06c22910f93808977137fb413c903324bb2f15112ad88bbe282150869f5b4bd4 |
| header | Thomas-Signature: t=1757930000,v1=06c22910f93808977137fb413c903324bb2f15112ad88bbe282150869f5b4bd4 |
Mid-rotation. A verifier that checks only the first v1 fails this vector, which is the
single most common real defect: it passes every single-signature vector above and then breaks
in production the first time you rotate. Test it with the PREVIOUS secret (version 1) — the
one whose value is second.
| field | value |
|---|
t | 1757930000 |
| body | {"id":"018f3a5c-7b21-8c4d-9e6f-0a1b2c3d4e5f","type":"assessment.completed","version":1,"occurredAt":"2025-09-15T09:53:12.000Z","tenantId":"4f9c1e2a-6d3b-4a15-9c8e-2b7d0f5a1c34","sequence":4,"data":{"assignmentId":"7c2e9a10-5f4b-4d83-b1a6-9e0c3d7f2b58","subjectId":"2a6f8c31-0b95-4e27-8d14-6c3a9f5b7e02","relationshipType":"employee","origin":"recruitment","resultId":"9d1b4e76-3c82-4f09-a5d7-1e8b6c40f293"}} |
| secret, version 2 (active) | M-g1X0N3SStx-4g9pNt46Cxl02ZQkbyUid7M3RyAt_8 |
| secret, version 1 (overlap) | CVjxZry3CPr1awYKmRay7qHMl_2Jo2Pa4I0DV1L4V9g |
| header | Thomas-Signature: t=1757930000,v1=841259adaec32f2e70de8a51d31a003df1ffe038166d3de41a6073aadb3021cd,v1=9b4d2f82c89f39c7a2780f4363b9cd3f97d6e9fca8696a73ef4555e6af499a51 |
Version 1's value is the same digest envelope-assessment-completed publishes — the body and
timestamp are identical and so is the secret. It was derived with the other tool, so the two
agree across openssl and python3.
tampered-body — a header that must be REJECTED
Every vector above must verify, so an implementation hardcoded to accept passes all of them.
This one must fail. The header is genuine — Thomas really emitted it — but one byte of
the body was altered in flight ("sequence":4 became "sequence":5).
| field | value |
|---|
t | 1757930000 |
| body as received | {"id":"018f3a5c-7b21-8c4d-9e6f-0a1b2c3d4e5f","type":"assessment.completed","version":1,"occurredAt":"2025-09-15T09:53:12.000Z","tenantId":"4f9c1e2a-6d3b-4a15-9c8e-2b7d0f5a1c34","sequence":5,"data":{"assignmentId":"7c2e9a10-5f4b-4d83-b1a6-9e0c3d7f2b58","subjectId":"2a6f8c31-0b95-4e27-8d14-6c3a9f5b7e02","relationshipType":"employee","origin":"recruitment","resultId":"9d1b4e76-3c82-4f09-a5d7-1e8b6c40f293"}} |
| secret | CVjxZry3CPr1awYKmRay7qHMl_2Jo2Pa4I0DV1L4V9g |
| header as received | Thomas-Signature: t=1757930000,v1=9b4d2f82c89f39c7a2780f4363b9cd3f97d6e9fca8696a73ef4555e6af499a51 |
| what this body honestly signs to | 9ead717843f51731dca42e0c91d77ea9135024f4d6e49fc58737574a6781a12c |
Your verifier must compute the last value and find it absent from the header. If it accepts
this request, check that it compares the computed signature with the received header and
hashes the actual received body. Parsing and re-serialising still preserves the changed
sequence value; the unicode-escape and key-order-variant vectors separately expose
raw-byte normalisation defects.
8. What can change, and what cannot
Frozen for the life of v1: the signed string <t>.<raw request body>, the Thomas-Signature header
name, the t and v1 parameter names, t in Unix seconds, HMAC-SHA256, lowercase hex, the
secret string as the key, and the vectors above.
Additive and safe to expect: more v1 values during a rotation, new parameter names
alongside t and v1, and new vectors appended to the set. A verifier written to this page
— ignore unrecognised parameter names, try every v1 — needs no change for any of them.
The tolerance of 300 seconds is the widest window to accept: you may enforce a narrower
window if your clocks are tight, but do not widen it.