Webhooks

Consume Thomas events

Thomas sends a signed HTTPS POST to the endpoint you register whenever an event your Grant covers happens. Here is what each event means, how delivery behaves, and how to verify a signature.

Consume webhooks

React to events without polling

Register an endpoint, verify every request Thomas sends it, and process each event once even when Thomas delivers it again.

  1. 1
    Request a token

    Exchange your client credentials for an access token. It lasts one hour, so request a new one when it expires.

    Request
    curl -X POST "$THOMAS_TOKEN_URL" \
      -u "$THOMAS_CLIENT_ID:$THOMAS_CLIENT_SECRET" \
      -d grant_type=client_credentials
  2. 2
    Register your endpoint

    Register the public HTTPS URL Thomas should deliver your events to. The response carries the signing secret once, in this response only, so store it securely before you do anything else: you cannot read it back later. The Idempotency-Key header is required: reuse the same key when you retry, so a retried registration returns the same subscription and secret instead of a second one.

    POSThttps://staging-api.thomas.co/v1/webhook-subscriptions
    Request
    POST /webhook-subscriptions
    { "endpointUrl": "https://hooks.example.com/thomas" }
    Response
    {
      "subscriptionId": "00000000-0000-4000-8000-000000000051",
      "endpointUrl": "https://hooks.example.com/thomas",
      "signingSecret": "ex4mple-signing-secret-shown-once-000000000",
      "signingSecretVersion": 1,
      "activatedAt": "2026-10-01T00:00:00.000Z",
      "createdAt": "2026-10-01T00:00:00.000Z"
    }
  3. 3
    Verify every requestyour system

    Before you trust a request, verify its Thomas-Signature header against the raw request body with your signing secret, and reject it if its timestamp is more than 300 seconds from your clock. Follow the walkthrough at /webhooks#webhook-signature-verification, and run your verifier against the published test vectors before you go live.

  4. 4
    Deduplicate, then acknowledge fastyour system

    Thomas can deliver the same event more than once, and every redelivery carries the same event id. Store each verified event durably, under a unique key on its id, in one step. Only then answer any 2xx within 10 seconds, and process the stored event afterwards: an answer that takes longer is a timeout, and Thomas sends the event again. If the id is already stored, it is a redelivery: answer 2xx and skip it. If the store fails, do not answer 2xx.

  5. 5
    Read what happened to a delivery

    Look up one delivery by the event id the webhook carried, to tell an event Thomas has not sent yet from one your endpoint rejected. You see only your own deliveries in this tenant.

    GEThttps://staging-api.thomas.co/v1/webhook-deliveries/{eventId}
    Request
    GET /webhook-deliveries/00000000-0000-4000-8000-000000000061
    Response
    {
      "eventId": "00000000-0000-4000-8000-000000000061",
      "eventType": "assessment.completed",
      "tenantId": "00000000-0000-4000-8000-000000000001",
      "status": "delivered",
      "attemptCount": 2,
      "lastAttemptAt": "2026-10-01T00:01:02.000Z",
      "nextAttemptAt": null,
      "lastHttpStatus": 200,
      "lastFailureCategory": null,
      "createdAt": "2026-10-01T00:00:00.000Z"
    }
Build this with your agent
Open with ClaudeOpen with ChatGPT
Open these calls in the API reference

Event reference

Every event Thomas publishes. The payload fields and their meanings come from the same contract Thomas signs each event with.

assessment.assigned

v1onAssessmentAssigned

An assessment was assigned to a subject. The payload names the assignment and an opaque subject reference, never a name or email.

Delivery. Ordered per assignment by sequence: strictly increasing, with gaps allowed. Events can arrive out of order, and a retry can arrive after a newer event. Thomas retries an attempt that gets no answer, a 408, a 429 or a 5xx for up to 24 hours; any other failure stops it sooner, as How Thomas delivers a webhook explains.

assessment.assigned payload fields
FieldTypeMeaning
assignmentIduuidThe assignment this event belongs to. sequence orders events per assignment.
subjectIduuidOpaque reference to the subject, unique to your API Client. Never a name, email or other identity value.
relationshipType"employee" | "candidate"The subject's relationship to the tenant: employee or candidate.
origin"employment" | "recruitment"Whether the assessment came through employment or recruitment. Independent of relationshipType.
Envelope fields
assessment.assigned envelope fields
FieldTypeMeaning
iduuidStable event id. Every redelivery of this event carries the same id, so deduplicate on it.
type"assessment.assigned"The event type: always assessment.assigned for this event. Route on it.
version1Contract version, always 1. Ignore unknown fields: v1 changes only additively, and a breaking change ships as a new version.
occurredAtdate-timeWhen the event occurred, as a UTC RFC 3339 timestamp ending in Z.
tenantIduuidThe tenant the event belongs to.
dataobjectThe assignment, its subject and how the subject relates to the tenant.
actoroptionalobjectPresent only when the fact was recorded while a partner acted on behalf of a named person.
actor.companyIndividualIduuidThe person the partner acted for: their Company Individual in this tenant.
actor.viaobjectThe partner channel the person acted through.
actor.via.ownerIduuidThe Partner that owns the API Client the person acted through.
actor.via.apiClientIduuidThe API Client that made the call.
actor.via.credentialIduuidThe Credential the API Client used for the call.
actor.via.grantIduuidThe Grant that authorised the call in this tenant.
actor.via.scopestringspace-delimited Grant Scopes this operation actually used
sequenceintegerOrders this aggregate's events: strictly increasing, with gaps allowed, so a gap never proves a delivery is missing.

assessment.completed

v1onAssessmentCompleted

A subject completed an assessment and its result exists. The event carries no score: fetch the result named by resultId through the results API.

Delivery. Ordered per assignment by sequence: strictly increasing, with gaps allowed. Events can arrive out of order, and a retry can arrive after a newer event. Thomas retries an attempt that gets no answer, a 408, a 429 or a 5xx for up to 24 hours; any other failure stops it sooner, as How Thomas delivers a webhook explains.

assessment.completed payload fields
FieldTypeMeaning
assignmentIduuidThe assignment this event belongs to. sequence orders events per assignment.
subjectIduuidOpaque reference to the subject, unique to your API Client. Never a name, email or other identity value.
relationshipType"employee" | "candidate"The subject's relationship to the tenant: employee or candidate.
origin"employment" | "recruitment"Whether the assessment came through employment or recruitment. Independent of relationshipType.
resultIduuidThe result to fetch through the results API. No score is sent in the event.
Envelope fields
assessment.completed envelope fields
FieldTypeMeaning
iduuidStable event id. Every redelivery of this event carries the same id, so deduplicate on it.
type"assessment.completed"The event type: always assessment.completed for this event. Route on it.
version1Contract version, always 1. Ignore unknown fields: v1 changes only additively, and a breaking change ships as a new version.
occurredAtdate-timeWhen the event occurred, as a UTC RFC 3339 timestamp ending in Z.
tenantIduuidThe tenant the event belongs to.
dataobjectThe assignment, its subject and the result to fetch. No scores.
actoroptionalobjectPresent only when the fact was recorded while a partner acted on behalf of a named person.
actor.companyIndividualIduuidThe person the partner acted for: their Company Individual in this tenant.
actor.viaobjectThe partner channel the person acted through.
actor.via.ownerIduuidThe Partner that owns the API Client the person acted through.
actor.via.apiClientIduuidThe API Client that made the call.
actor.via.credentialIduuidThe Credential the API Client used for the call.
actor.via.grantIduuidThe Grant that authorised the call in this tenant.
actor.via.scopestringspace-delimited Grant Scopes this operation actually used
sequenceintegerOrders this aggregate's events: strictly increasing, with gaps allowed, so a gap never proves a delivery is missing.

assessment.expired

v1onAssessmentExpired

An assigned assessment expired before the subject completed it. When its deadline passes, Thomas sends this event once the deadline is more than 24 hours past (within about 15 minutes after that), with occurredAt set to the deadline itself.

Delivery. Ordered per assignment by sequence: strictly increasing, with gaps allowed. Events can arrive out of order, and a retry can arrive after a newer event. Thomas retries an attempt that gets no answer, a 408, a 429 or a 5xx for up to 24 hours; any other failure stops it sooner, as How Thomas delivers a webhook explains.

assessment.expired payload fields
FieldTypeMeaning
assignmentIduuidThe assignment this event belongs to. sequence orders events per assignment.
subjectIduuidOpaque reference to the subject, unique to your API Client. Never a name, email or other identity value.
relationshipType"employee" | "candidate"The subject's relationship to the tenant: employee or candidate.
origin"employment" | "recruitment"Whether the assessment came through employment or recruitment. Independent of relationshipType.
Envelope fields
assessment.expired envelope fields
FieldTypeMeaning
iduuidStable event id. Every redelivery of this event carries the same id, so deduplicate on it.
type"assessment.expired"The event type: always assessment.expired for this event. Route on it.
version1Contract version, always 1. Ignore unknown fields: v1 changes only additively, and a breaking change ships as a new version.
occurredAtdate-timeWhen the event occurred, as a UTC RFC 3339 timestamp ending in Z.
tenantIduuidThe tenant the event belongs to.
dataobjectThe assignment, its subject and how the subject relates to the tenant.
actoroptionalobjectPresent only when the fact was recorded while a partner acted on behalf of a named person.
actor.companyIndividualIduuidThe person the partner acted for: their Company Individual in this tenant.
actor.viaobjectThe partner channel the person acted through.
actor.via.ownerIduuidThe Partner that owns the API Client the person acted through.
actor.via.apiClientIduuidThe API Client that made the call.
actor.via.credentialIduuidThe Credential the API Client used for the call.
actor.via.grantIduuidThe Grant that authorised the call in this tenant.
actor.via.scopestringspace-delimited Grant Scopes this operation actually used
sequenceintegerOrders this aggregate's events: strictly increasing, with gaps allowed, so a gap never proves a delivery is missing.

assessment.started

v1onAssessmentStarted

A subject started an assessment that was assigned to them.

Delivery. Ordered per assignment by sequence: strictly increasing, with gaps allowed. Events can arrive out of order, and a retry can arrive after a newer event. Thomas retries an attempt that gets no answer, a 408, a 429 or a 5xx for up to 24 hours; any other failure stops it sooner, as How Thomas delivers a webhook explains.

assessment.started payload fields
FieldTypeMeaning
assignmentIduuidThe assignment this event belongs to. sequence orders events per assignment.
subjectIduuidOpaque reference to the subject, unique to your API Client. Never a name, email or other identity value.
relationshipType"employee" | "candidate"The subject's relationship to the tenant: employee or candidate.
origin"employment" | "recruitment"Whether the assessment came through employment or recruitment. Independent of relationshipType.
Envelope fields
assessment.started envelope fields
FieldTypeMeaning
iduuidStable event id. Every redelivery of this event carries the same id, so deduplicate on it.
type"assessment.started"The event type: always assessment.started for this event. Route on it.
version1Contract version, always 1. Ignore unknown fields: v1 changes only additively, and a breaking change ships as a new version.
occurredAtdate-timeWhen the event occurred, as a UTC RFC 3339 timestamp ending in Z.
tenantIduuidThe tenant the event belongs to.
dataobjectThe assignment, its subject and how the subject relates to the tenant.
actoroptionalobjectPresent only when the fact was recorded while a partner acted on behalf of a named person.
actor.companyIndividualIduuidThe person the partner acted for: their Company Individual in this tenant.
actor.viaobjectThe partner channel the person acted through.
actor.via.ownerIduuidThe Partner that owns the API Client the person acted through.
actor.via.apiClientIduuidThe API Client that made the call.
actor.via.credentialIduuidThe Credential the API Client used for the call.
actor.via.grantIduuidThe Grant that authorised the call in this tenant.
actor.via.scopestringspace-delimited Grant Scopes this operation actually used
sequenceintegerOrders this aggregate's events: strictly increasing, with gaps allowed, so a gap never proves a delivery is missing.

checkin.cancelled

v1onCheckinCancelled

A team check-in run was withdrawn before it closed.

Delivery. Ordered per run by sequence. A terminal event can arrive with no checkin.deployed before it, for a run that opened before you were covered: treat it as a closed run you never saw open. Thomas retries an attempt that gets no answer, a 408, a 429 or a 5xx for up to 24 hours; any other failure stops it sooner, as How Thomas delivers a webhook explains.

checkin.cancelled payload fields
FieldTypeMeaning
runIduuidThe check-in run. sequence orders events per run.
teamIduuidThe team the check-in run belongs to.
Envelope fields
checkin.cancelled envelope fields
FieldTypeMeaning
iduuidStable event id. Every redelivery of this event carries the same id, so deduplicate on it.
type"checkin.cancelled"The event type: always checkin.cancelled for this event. Route on it.
version1Contract version, always 1. Ignore unknown fields: v1 changes only additively, and a breaking change ships as a new version.
occurredAtdate-timeWhen the event occurred, as a UTC RFC 3339 timestamp ending in Z.
tenantIduuidThe tenant the event belongs to.
dataobjectThe check-in run and its team. No person or score.
actoroptionalobjectPresent only when the fact was recorded while a partner acted on behalf of a named person.
actor.companyIndividualIduuidThe person the partner acted for: their Company Individual in this tenant.
actor.viaobjectThe partner channel the person acted through.
actor.via.ownerIduuidThe Partner that owns the API Client the person acted through.
actor.via.apiClientIduuidThe API Client that made the call.
actor.via.credentialIduuidThe Credential the API Client used for the call.
actor.via.grantIduuidThe Grant that authorised the call in this tenant.
actor.via.scopestringspace-delimited Grant Scopes this operation actually used
sequenceintegerOrders this aggregate's events: strictly increasing, with gaps allowed, so a gap never proves a delivery is missing.

checkin.completed

v1onCheckinCompleted

A team check-in run closed, because every member answered or its due date passed. It does not mean a team result was produced.

Delivery. Ordered per run by sequence. A terminal event can arrive with no checkin.deployed before it, for a run that opened before you were covered: treat it as a closed run you never saw open. Thomas retries an attempt that gets no answer, a 408, a 429 or a 5xx for up to 24 hours; any other failure stops it sooner, as How Thomas delivers a webhook explains.

checkin.completed payload fields
FieldTypeMeaning
runIduuidThe check-in run. sequence orders events per run.
teamIduuidThe team the check-in run belongs to.
Envelope fields
checkin.completed envelope fields
FieldTypeMeaning
iduuidStable event id. Every redelivery of this event carries the same id, so deduplicate on it.
type"checkin.completed"The event type: always checkin.completed for this event. Route on it.
version1Contract version, always 1. Ignore unknown fields: v1 changes only additively, and a breaking change ships as a new version.
occurredAtdate-timeWhen the event occurred, as a UTC RFC 3339 timestamp ending in Z.
tenantIduuidThe tenant the event belongs to.
dataobjectThe check-in run and its team. No person or score.
actoroptionalobjectPresent only when the fact was recorded while a partner acted on behalf of a named person.
actor.companyIndividualIduuidThe person the partner acted for: their Company Individual in this tenant.
actor.viaobjectThe partner channel the person acted through.
actor.via.ownerIduuidThe Partner that owns the API Client the person acted through.
actor.via.apiClientIduuidThe API Client that made the call.
actor.via.credentialIduuidThe Credential the API Client used for the call.
actor.via.grantIduuidThe Grant that authorised the call in this tenant.
actor.via.scopestringspace-delimited Grant Scopes this operation actually used
sequenceintegerOrders this aggregate's events: strictly increasing, with gaps allowed, so a gap never proves a delivery is missing.

checkin.deployed

v1onCheckinDeployed

A team check-in run opened. No person or score is sent.

Delivery. Ordered per run by sequence, starting at 1. Exactly one terminal event, checkin.completed or checkin.cancelled, follows for the run. Thomas retries an attempt that gets no answer, a 408, a 429 or a 5xx for up to 24 hours; any other failure stops it sooner, as How Thomas delivers a webhook explains.

checkin.deployed payload fields
FieldTypeMeaning
runIduuidThe check-in run. sequence orders events per run.
teamIduuidThe team the check-in run belongs to.
Envelope fields
checkin.deployed envelope fields
FieldTypeMeaning
iduuidStable event id. Every redelivery of this event carries the same id, so deduplicate on it.
type"checkin.deployed"The event type: always checkin.deployed for this event. Route on it.
version1Contract version, always 1. Ignore unknown fields: v1 changes only additively, and a breaking change ships as a new version.
occurredAtdate-timeWhen the event occurred, as a UTC RFC 3339 timestamp ending in Z.
tenantIduuidThe tenant the event belongs to.
dataobjectThe check-in run and its team. No person or score.
actoroptionalobjectPresent only when the fact was recorded while a partner acted on behalf of a named person.
actor.companyIndividualIduuidThe person the partner acted for: their Company Individual in this tenant.
actor.viaobjectThe partner channel the person acted through.
actor.via.ownerIduuidThe Partner that owns the API Client the person acted through.
actor.via.apiClientIduuidThe API Client that made the call.
actor.via.credentialIduuidThe Credential the API Client used for the call.
actor.via.grantIduuidThe Grant that authorised the call in this tenant.
actor.via.scopestringspace-delimited Grant Scopes this operation actually used
sequenceintegerOrders this aggregate's events: strictly increasing, with gaps allowed, so a gap never proves a delivery is missing.

dsr.completed

v1onDsrCompleted

A data subject request for a person in the tenant named by tenantId was fulfilled. Purge what you hold for that subjectId in that tenant.

Delivery. Carries no sequence. Thomas never abandons it: if it cannot be delivered, Thomas keeps it open and waits for the cause to be fixed instead of recording it as failed, and any resend carries the same id. You can receive individual.anonymised for the same subjectId too, in either order.

dsr.completed payload fields
FieldTypeMeaning
subjectIduuidOpaque reference to the subject, the same one you received on earlier events. Purge what you hold for it in this tenant.
Envelope fields
dsr.completed envelope fields
FieldTypeMeaning
iduuidStable event id. Every redelivery of this event carries the same id, so deduplicate on it.
type"dsr.completed"The event type: always dsr.completed for this event. Route on it.
version1Contract version, always 1. Ignore unknown fields: v1 changes only additively, and a breaking change ships as a new version.
occurredAtdate-timeWhen the event occurred, as a UTC RFC 3339 timestamp ending in Z.
tenantIduuidThe tenant the event belongs to.
dataobjectThe subject whose data subject request was fulfilled in this tenant.

grant.approved

v1onGrantApproved

The customer approved your pending connection to the tenant named by tenantId, so its Grant is now active and you can start reading on the scope you requested.

Delivery. Carries no sequence. Thomas never abandons it: if it cannot be delivered, Thomas keeps it open and waits for the cause to be fixed instead of recording it as failed, and any resend carries the same id. If you have not registered an endpoint yet, it waits and is sent once one is active.

grant.approved payload fields
FieldTypeMeaning
grantIduuidThe approved Grant. A re-request creates a new Grant, so this id tells approval cycles apart.
Envelope fields
grant.approved envelope fields
FieldTypeMeaning
iduuidStable event id. Every redelivery of this event carries the same id, so deduplicate on it.
type"grant.approved"The event type: always grant.approved for this event. Route on it.
version1Contract version, always 1. Ignore unknown fields: v1 changes only additively, and a breaking change ships as a new version.
occurredAtdate-timeWhen the event occurred, as a UTC RFC 3339 timestamp ending in Z.
tenantIduuidThe tenant the event belongs to.
dataobjectThe approved Grant. Read its Scope from GET /v1/tenants.

grant.revoked

v1onGrantRevoked

The customer revoked your connection to the tenant named by tenantId, at occurredAt. It is sent only to the API client whose Grant was revoked, and data is always empty. A notice that was kept waiting can arrive after the customer connected you again, so request a token for that tenant to check your access now.

Delivery. Carries no sequence. Thomas never abandons it: if it cannot be delivered, Thomas keeps it open and waits for the cause to be fixed instead of recording it as failed, and any resend carries the same id. If you have not registered an endpoint yet, it waits and is sent once one is active. Data events still waiting when your access was revoked are not sent.

Payload. Always empty. The envelope tenantId and occurredAt say which tenant revoked your access and when.

Envelope fields
grant.revoked envelope fields
FieldTypeMeaning
iduuidStable event id. Every redelivery of this event carries the same id, so deduplicate on it.
type"grant.revoked"The event type: always grant.revoked for this event. Route on it.
version1Contract version, always 1. Ignore unknown fields: v1 changes only additively, and a breaking change ships as a new version.
occurredAtdate-timeWhen the event occurred, as a UTC RFC 3339 timestamp ending in Z.
tenantIduuidThe tenant the event belongs to.
dataobjectAlways empty. The envelope tenantId and occurredAt say which tenant revoked your access and when.

individual.anonymised

v1onIndividualAnonymised

Thomas anonymised a person's data in the tenant named by tenantId. Purge what you hold for that subjectId in that tenant. It does not mean the person was erased everywhere.

Delivery. Carries no sequence. Thomas never abandons it: if it cannot be delivered, Thomas keeps it open and waits for the cause to be fixed instead of recording it as failed, and any resend carries the same id. You can receive dsr.completed for the same subjectId too, in either order.

individual.anonymised payload fields
FieldTypeMeaning
subjectIduuidOpaque reference to the subject, the same one you received on earlier events. Purge what you hold for it in this tenant.
Envelope fields
individual.anonymised envelope fields
FieldTypeMeaning
iduuidStable event id. Every redelivery of this event carries the same id, so deduplicate on it.
type"individual.anonymised"The event type: always individual.anonymised for this event. Route on it.
version1Contract version, always 1. Ignore unknown fields: v1 changes only additively, and a breaking change ships as a new version.
occurredAtdate-timeWhen the event occurred, as a UTC RFC 3339 timestamp ending in Z.
tenantIduuidThe tenant the event belongs to.
dataobjectThe subject whose data was anonymised in this tenant.

result.invalidated

v1onResultInvalidated

Thomas withdrew a result you hold. Stop showing it, and purge what you hold for that resultId.

Delivery. Carries no sequence. Thomas never abandons it: if it cannot be delivered, Thomas keeps it open and waits for the cause to be fixed instead of recording it as failed, and any resend carries the same id.

result.invalidated payload fields
FieldTypeMeaning
resultIduuidThe result, the same id you received as data.resultId on assessment.completed.
subjectIduuidOpaque reference to the subject, the same one you received on earlier events.
Envelope fields
result.invalidated envelope fields
FieldTypeMeaning
iduuidStable event id. Every redelivery of this event carries the same id, so deduplicate on it.
type"result.invalidated"The event type: always result.invalidated for this event. Route on it.
version1Contract version, always 1. Ignore unknown fields: v1 changes only additively, and a breaking change ships as a new version.
occurredAtdate-timeWhen the event occurred, as a UTC RFC 3339 timestamp ending in Z.
tenantIduuidThe tenant the event belongs to.
dataobjectThe withdrawn result and its subject. Stop showing that result.
actoroptionalobjectPresent only when the fact was recorded while a partner acted on behalf of a named person.
actor.companyIndividualIduuidThe person the partner acted for: their Company Individual in this tenant.
actor.viaobjectThe partner channel the person acted through.
actor.via.ownerIduuidThe Partner that owns the API Client the person acted through.
actor.via.apiClientIduuidThe API Client that made the call.
actor.via.credentialIduuidThe Credential the API Client used for the call.
actor.via.grantIduuidThe Grant that authorised the call in this tenant.
actor.via.scopestringspace-delimited Grant Scopes this operation actually used

result.updated

v1onResultUpdated

A result you already hold changed, for example after a re-score. Fetch the result named by resultId again to see what changed.

Delivery. Carries no sequence. Events can arrive out of order. Thomas retries an attempt that gets no answer, a 408, a 429 or a 5xx for up to 24 hours; any other failure stops it sooner, as How Thomas delivers a webhook explains.

result.updated payload fields
FieldTypeMeaning
resultIduuidThe result, the same id you received as data.resultId on assessment.completed.
subjectIduuidOpaque reference to the subject, the same one you received on earlier events.
Envelope fields
result.updated envelope fields
FieldTypeMeaning
iduuidStable event id. Every redelivery of this event carries the same id, so deduplicate on it.
type"result.updated"The event type: always result.updated for this event. Route on it.
version1Contract version, always 1. Ignore unknown fields: v1 changes only additively, and a breaking change ships as a new version.
occurredAtdate-timeWhen the event occurred, as a UTC RFC 3339 timestamp ending in Z.
tenantIduuidThe tenant the event belongs to.
dataobjectThe changed result and its subject. Fetch the current result to see what changed.
actoroptionalobjectPresent only when the fact was recorded while a partner acted on behalf of a named person.
actor.companyIndividualIduuidThe person the partner acted for: their Company Individual in this tenant.
actor.viaobjectThe partner channel the person acted through.
actor.via.ownerIduuidThe Partner that owns the API Client the person acted through.
actor.via.apiClientIduuidThe API Client that made the call.
actor.via.credentialIduuidThe Credential the API Client used for the call.
actor.via.grantIduuidThe Grant that authorised the call in this tenant.
actor.via.scopestringspace-delimited Grant Scopes this operation actually used

session.completed

v1onSessionCompleted

A team session was completed. It is sent once per session.

Delivery. Ordered per session by sequence. A session.completed can arrive with no session.created before it: treat it as a completed session you never saw start. Thomas retries an attempt that gets no answer, a 408, a 429 or a 5xx for up to 24 hours; any other failure stops it sooner, as How Thomas delivers a webhook explains.

session.completed payload fields
FieldTypeMeaning
sessionIduuidThe team session. sequence orders events per session.
teamIduuidThe team the session belongs to.
Envelope fields
session.completed envelope fields
FieldTypeMeaning
iduuidStable event id. Every redelivery of this event carries the same id, so deduplicate on it.
type"session.completed"The event type: always session.completed for this event. Route on it.
version1Contract version, always 1. Ignore unknown fields: v1 changes only additively, and a breaking change ships as a new version.
occurredAtdate-timeWhen the event occurred, as a UTC RFC 3339 timestamp ending in Z.
tenantIduuidThe tenant the event belongs to.
dataobjectThe session and its team. No person or free text.
actoroptionalobjectPresent only when the fact was recorded while a partner acted on behalf of a named person.
actor.companyIndividualIduuidThe person the partner acted for: their Company Individual in this tenant.
actor.viaobjectThe partner channel the person acted through.
actor.via.ownerIduuidThe Partner that owns the API Client the person acted through.
actor.via.apiClientIduuidThe API Client that made the call.
actor.via.credentialIduuidThe Credential the API Client used for the call.
actor.via.grantIduuidThe Grant that authorised the call in this tenant.
actor.via.scopestringspace-delimited Grant Scopes this operation actually used
sequenceintegerOrders this aggregate's events: strictly increasing, with gaps allowed, so a gap never proves a delivery is missing.

session.created

v1onSessionCreated

A team session started. A session that is planned and then discarded is never sent.

Delivery. Ordered per session by sequence. Events can arrive out of order, and a gap in sequence never proves a delivery is missing. Thomas retries an attempt that gets no answer, a 408, a 429 or a 5xx for up to 24 hours; any other failure stops it sooner, as How Thomas delivers a webhook explains.

session.created payload fields
FieldTypeMeaning
sessionIduuidThe team session. sequence orders events per session.
teamIduuidThe team the session belongs to.
Envelope fields
session.created envelope fields
FieldTypeMeaning
iduuidStable event id. Every redelivery of this event carries the same id, so deduplicate on it.
type"session.created"The event type: always session.created for this event. Route on it.
version1Contract version, always 1. Ignore unknown fields: v1 changes only additively, and a breaking change ships as a new version.
occurredAtdate-timeWhen the event occurred, as a UTC RFC 3339 timestamp ending in Z.
tenantIduuidThe tenant the event belongs to.
dataobjectThe session and its team. No person or free text.
actoroptionalobjectPresent only when the fact was recorded while a partner acted on behalf of a named person.
actor.companyIndividualIduuidThe person the partner acted for: their Company Individual in this tenant.
actor.viaobjectThe partner channel the person acted through.
actor.via.ownerIduuidThe Partner that owns the API Client the person acted through.
actor.via.apiClientIduuidThe API Client that made the call.
actor.via.credentialIduuidThe Credential the API Client used for the call.
actor.via.grantIduuidThe Grant that authorised the call in this tenant.
actor.via.scopestringspace-delimited Grant Scopes this operation actually used
sequenceintegerOrders this aggregate's events: strictly increasing, with gaps allowed, so a gap never proves a delivery is missing.

How Thomas delivers a webhook

This page describes what Thomas does when it sends an event to your endpoint: how long it waits, which answers count as delivered, when it retries, and when it stops. For how to check that a request really came from Thomas, see webhook-signature-verification.md.

1. One attempt

Each attempt is one HTTPS POST of the signed JSON event to your registered endpoint.

  • Any 2xx status means delivered. Thomas stops sending that event to you.
  • The whole attempt has 10 seconds. That covers connecting, the TLS handshake, sending the body and receiving your status line. An endpoint that has not answered in 10 seconds has timed out, even if it is still sending bytes. Acknowledge quickly and do your processing afterwards.
  • Redirects are never followed. A 3xx answer is treated as a failure, and Thomas never connects to the Location it names.
  • Thomas reads only your status line and headers. The response body is ignored.

2. Which failures are retried

Your endpoint's answerWhat Thomas does
2xxDelivered. No further attempts.
No answer: connection refused or reset, a TLS failure, or the 10-second timeoutRetries on the schedule below.
408, 429, or any 5xxRetries on the schedule below.
3xxStops after this attempt. The event is not delivered.
Any other 4xx (400, 401, 403, 404, 410, …)Stops after this attempt. The event is not delivered.

Before every attempt, including every retry, Thomas checks your endpoint's address again. If the address is refused (for example, it now points at a private network), that attempt fails without a request being made, and the next attempt follows the schedule.

3. The retry schedule

Attempts are measured from the event's first attempt. Each retry falls at about the time listed, and can be up to a short polling delay (normally under a minute) later:

AttemptTime after the first attempt
1immediately
21 minute
35 minutes
415 minutes
51 hour
63 hours
76 hours
812 hours
924 hours (in practice just under)
  • At most 9 attempts in one set. If the ninth attempt is not delivered, Thomas stops, and the event is recorded as failed. (A compliance notice is kept open instead; see section 7.) When a Thomas operator resends an event that Thomas was holding open (sections 5 and 7), the resend starts a new set of up to nine attempts on this schedule, with the same event id.
  • Each retry moves by up to ±10% of the gap before it, so retries from many events do not all arrive at once. For example, attempt 2 is scheduled between 54 and 66 seconds after the first, and is made at the next poll after that.
  • 24 hours is a hard limit. The last attempt is made just before the 24-hour mark, and no attempt is ever made after it: if an attempt cannot start in time (for example, after an outage on Thomas's side), it is not made and the event is recorded as failed instead.

Retry-After

If you answer 429 or 503 with a Retry-After header, Thomas does not retry before the time you asked for. It never retries sooner than the schedule, either: the later of the two wins. Two forms are accepted: a whole number of seconds (Retry-After: 120) or an HTTP date in the standard form (Retry-After: Mon, 28 Sep 2026 09:02:00 GMT). Any other value is ignored, and the schedule applies.

If the time you ask for is past the 24-hour limit, Thomas stops rather than retrying early, and the event is recorded as failed.

Retry-After is ignored on every other status.

4. What stays the same across retries

  • The event id never changes. Every attempt at the same event carries the same id. Use it to deduplicate: in rare cases, such as Thomas recovering from a restart, you can receive the same event more than once.
  • The signature is new on every attempt. Each attempt has a fresh t timestamp in its Thomas-Signature header, so a retry is never rejected as a stale replay.

5. When Thomas stops without retrying

  • Your access was removed. Before every attempt Thomas checks that you are still authorised to receive the event. If you are not (for example, the customer revoked your access), Thomas stops and sends nothing more for that event. The exceptions are the grant.revoked event that tells you about the revocation itself and compliance notices about data you already received (section 7).
  • Your subscription was removed or disabled. Thomas stops, and sends nothing more for that event. (A compliance notice waits for the subscription instead; see section 7.)
  • Your subscription has no valid signing secret. Every signing secret on it has been retired or has expired. Thomas never sends an unsigned event, so it stops, records the event as failed and sends nothing more for it. Rotate in a new signing secret for later events. (A compliance notice waits for the new secret instead; see section 7.)
  • The event could not be built, or Thomas could not use its own signing key. This is a problem on Thomas's side, and nothing is sent. Thomas keeps the event open rather than recording it as failed: once the problem is fixed, a Thomas operator can send it to you later, with the same event id, starting a new set of up to nine attempts (section 3), or, if it will not be sent, records it as failed. Until then it is not retried. Its status (section 8) is retrying with nextAttemptAt: null.
  • A persistent error on Thomas's side. If Thomas cannot complete an attempt because of an error of its own, it tries again at the next scheduled time. If that keeps happening, the event can be recorded as failed before all nine attempts have been made.

6. What a failed event does not do

A failed event never disables your subscription, and it never stops Thomas sending your other events: each event has its own attempts and its own schedule. Events are not delivered in a guaranteed order: a retry can arrive after a newer event.

7. Compliance and Grant notices are kept open until they are delivered

Three events tell you to stop holding or using data: result.invalidated, individual.anonymised and dsr.completed. grant.approved tells you that a customer approved your connection; grant.revoked tells you that a customer revoked it. Thomas keeps all five open until delivery or a documented manual closure. This includes the time before a webhook endpoint is registered: the notice waits until an endpoint is active.

result.invalidated currently has no trigger: nothing in Thomas withdraws a delivered result today, so you will not receive it. It stays in the event catalogue so its contract is stable if a trigger is added later.

The cases are:

Why it cannot be deliveredWhat Thomas does
Your partner account is suspended, or your API client is inactiveSends nothing, and waits. When your partner account is restored, Thomas sends the notice again automatically (for an inactive API client, see below).
Your subscription is missing or disabled, or it has no valid signing secretSends nothing, and waits. When you re-enable or recreate the subscription, or rotate in a new signing secret, Thomas sends the notice again automatically.
Your endpoint did not accept it (a 3xx, a non-retryable 4xx, all nine attempts failed, or a Retry-After past 24 hours)Stops this set of attempts and waits. Once you have fixed your endpoint, a Thomas operator can send it again.
A problem on Thomas's sideSends nothing, and waits for Thomas to fix it (section 5).

Every resend is a new set of up to nine attempts on the schedule in section 3, starting again from the first attempt. It carries the same event id, so deduplicate on it as usual, and a new signature, like any retry.

To ask for a resend once you have fixed your endpoint, contact Thomas support with the event's id. Section 8 shows which of your events are waiting: their status is retrying with no next attempt scheduled.

An inactive API client cannot be reactivated, so a notice waiting on one is not sent automatically. If you can confirm through another secure channel that you have already acted on the notice, a Thomas operator can close it on that basis.

grant.revoked

grant.revoked is sent only to the API client whose grant on the tenant was revoked, even though that grant no longer gives it access. Data events (assessment.*, checkin.* and result.updated) that were still waiting to be sent when it was revoked are not sent. Compliance notices about data you already received are still sent.

The notice carries no data: data is {}, and the event's tenantId and occurredAt say which tenant revoked your access and when. A notice that was kept waiting (see the table above) can arrive after the customer has connected you again, so do not treat it alone as proof that your access is gone now. Request a token for that tenant: if Thomas issues one, your access was restored after the revocation the notice describes.

While you have no active grant on the tenant, you cannot look up the delivery status of a grant.revoked event (section 8): both status requests for that tenant are refused with 403 AUTH_TENANT_NOT_GRANTED. If the customer connects you again with an active grant containing one of the read scopes in section 8, you can read your previous revoke delivery's status. Otherwise, contact Thomas support with the event's id.

8. Reading what happened to a delivery

You can look up the delivery status of the events Thomas addressed to your API client, so you can tell "Thomas never sent it" from "my endpoint rejected it":

  • GET /v1/webhook-deliveries lists your deliveries on one tenant, newest first.
  • GET /v1/webhook-deliveries/{eventId} returns one delivery, by the id the webhook carried.

Both need your API client's token, exactly one Thomas-Tenant-Id header, and an active grant on that tenant that includes at least one of assessments:r or results:r. Either scope is enough on its own; you do not need both. You only ever see your own API client's deliveries on that tenant, and only for event types your grant still covers: each delivery is checked against its event type's own permission, so a grant with only results:r sees result.updated deliveries but not assessment.* ones, and a grant with only assessments:r sees the reverse. Event types that need no permission (for example result.invalidated) are shown under any active grant. An active grant holding neither scope is refused with 403 AUTH_TENANT_NOT_GRANTED. An event id that is unknown, belongs to another API client, belongs to another tenant, or is of an event type your grant no longer covers gets the same 404 WEBHOOK_DELIVERY_NOT_FOUND, and such deliveries are left out of the list. If your grant on the tenant is no longer active, both requests are refused with 403 AUTH_TENANT_NOT_GRANTED and return no deliveries.

Other refusals:

ResponseWhen
400 WEBHOOK_DELIVERY_LIST_QUERY_INVALIDThe list's cursor was not one this operation issued, limit is not an integer from 1 to 100, or you sent another query parameter.
400 AUTH_TENANT_CONTEXT_INVALIDNo Thomas-Tenant-Id header, more than one, or a malformed one.
400 HTTP_BAD_REQUESTThe eventId in the path is not a UUID.
403 PRINCIPAL_TYPE_NOT_ALLOWEDThe caller is not a Partner API client (for example a signed-in person), or it is acting on behalf of a person.
429Your API client's rate limit was reached. The response carries the rate-limit headers; retry after the time they give.

The list returns at most limit items (default 50, maximum 100) and a nextCursor. Pass the nextCursor back as cursor to read the next page; it is null on the last page. There is no total count.

A delivery is kept for 30 days after it is delivered or recorded as failed. After that it is deleted: it drops out of the list, and reading it by eventId returns 404 WEBHOOK_DELIVERY_NOT_FOUND. A delivery that is still retrying is never deleted.

Each item has exactly these fields:

FieldMeaning
eventIdThe event's id, the same value the webhook carried.
eventTypeThe event type, for example assessment.completed.
tenantIdThe tenant the event belongs to.
statusdelivered, retrying or failed (below).
attemptCountEvery HTTP attempt made for the event so far.
lastAttemptAtWhen the latest attempt was made, or null if none has been.
nextAttemptAtWhen Thomas will next attempt the event, or null if no attempt is scheduled.
lastHttpStatusThe HTTP status your endpoint returned on the latest attempt that received one, or null if none did. That attempt can be earlier than the one lastFailureCategory describes: after a 503 and then a timeout, lastHttpStatus is 503 and lastFailureCategory is timeout.
lastFailureCategoryWhy the latest attempt did not deliver, or why Thomas stopped (below), or null.
createdAtWhen Thomas created the delivery.

status

statusWhat it means
deliveredYour endpoint answered with a 2xx.
retryingThomas has not finished with the event: it is waiting for its first or next attempt, or Thomas is holding it.
failedThomas has stopped attempting the event.

A retrying event with nextAttemptAt: null is being held by Thomas, and no attempt is scheduled until the hold is resolved. Either there is a problem on Thomas's side (section 5), or it is a compliance notice waiting for its cause to be fixed (section 7).

lastFailureCategory

CategoryWhose sideWhat happened
endpoint_rejectedYoursYour endpoint answered with a status that is not 2xx or 3xx. The status is in lastHttpStatus.
redirect_refusedYoursYour endpoint answered with a 3xx. Thomas never follows redirects.
timeoutYoursYour endpoint did not answer within 10 seconds.
connection_refusedYoursYour endpoint refused the connection.
connection_resetYoursThe connection was reset.
tls_errorYoursThe TLS handshake failed, for example because of the certificate.
network_errorYoursThe connection failed for another network reason.
endpoint_refusedYoursYour endpoint's address failed Thomas's check before the attempt (section 2), so no request was made.
endpoint_not_configuredYoursYour API client had no webhook subscription, or no valid signing secret, when the event was due.
delivery_window_elapsedNeitherThe 24-hour limit was reached before the event was delivered.
not_authorizedNeitherYour API client was no longer authorised to receive the event (for example, it or your partner account was deactivated or suspended), or its subscription was disabled (sections 5 and 7).
thomas_errorThomas'sA problem on Thomas's side, including a connection Thomas declined to open itself. Contact Thomas support with the eventId.

9. Reading the event body

Every event is one JSON object: the same frame for every event type, with that type's own fields in data. The event reference lists every field of every event type and what it means.

Ignore fields you do not recognise. Version 1 changes only additively: a later release can add a field to the event or to its data, and a consumer that rejects an unknown field breaks on the day one is added. A change that is not additive ships as a new version, never as an edit to version 1, so check version and handle only the versions you know.

Download the test vectors (.json)Run your verifier against every vector before you trust it.

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.

1. The header

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

  1. 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.
  2. 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.
  3. Build <t>.<raw request body> from the literal timestamp characters you just read and the raw body bytes.
  4. Compute HMAC-SHA256(key = your signing secret, message = that byte string) and render it as lowercase hex.
  5. 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.
  6. 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.

fieldvalue
t1757930000
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"}}
secretCVjxZry3CPr1awYKmRay7qHMl_2Jo2Pa4I0DV1L4V9g
expected v19b4d2f82c89f39c7a2780f4363b9cd3f97d6e9fca8696a73ef4555e6af499a51
headerThomas-Signature: t=1757930000,v1=9b4d2f82c89f39c7a2780f4363b9cd3f97d6e9fca8696a73ef4555e6af499a51
empty-body

An empty body. The signed string is still <t> + . and nothing more.

fieldvalue
t1757930001
body(empty)
secretiJFGtcpX3zGOJHAhk0UIyGfvwb5YF2N4DMi2rRv8JjI
expected v1defcec1f0a73bb8827fe17056d35669085b561077244cbe7bde2d5ffde2b998d
headerThomas-Signature: t=1757930001,v1=defcec1f0a73bb8827fe17056d35669085b561077244cbe7bde2d5ffde2b998d
multibyte-utf8

A literal U+00E9, which is two bytes. Hash bytes, not characters.

fieldvalue
t1757930002
body{"note":"café"}
secretzDfMZbEdWnpGy7E2aNpHsUrVpabuxt0_cBp0thhH8PI
expected v1b2f42ef92c2f9342d801c84306c4365bd8d5c98d878a7c2bd7f3f53cc46c90d8
headerThomas-Signature: t=1757930002,v1=b2f42ef92c2f9342d801c84306c4365bd8d5c98d878a7c2bd7f3f53cc46c90d8
unicode-escape

The same JSON value as the row above, escaped. Same t, same secret, DIFFERENT signature.

fieldvalue
t1757930002
body{"note":"caf\u00e9"}
secretzDfMZbEdWnpGy7E2aNpHsUrVpabuxt0_cBp0thhH8PI
expected v1bb23195a7d7bf4870818154ad7edf18da4135ee5364a129c17fef32ec9497fc4
headerThomas-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.

fieldvalue
t1757930004
body{"note":"1757930000.not-a-timestamp"}
secret2YqeFjOhv1O-cbBuKdsUMRYSJ6saZec7um_SJfCbsIQ
expected v18038ce209a8bb0b22f80568564b7beb0e6e0e7b92fdacb95fbdc4cff8beaec8b
headerThomas-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.

fieldvalue
t1757930000
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"}}
secretCVjxZry3CPr1awYKmRay7qHMl_2Jo2Pa4I0DV1L4V9g
expected v106c22910f93808977137fb413c903324bb2f15112ad88bbe282150869f5b4bd4
headerThomas-Signature: t=1757930000,v1=06c22910f93808977137fb413c903324bb2f15112ad88bbe282150869f5b4bd4

rotation-overlap — a header with TWO signatures

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.

fieldvalue
t1757930000
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
headerThomas-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).

fieldvalue
t1757930000
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"}}
secretCVjxZry3CPr1awYKmRay7qHMl_2Jo2Pa4I0DV1L4V9g
header as receivedThomas-Signature: t=1757930000,v1=9b4d2f82c89f39c7a2780f4363b9cd3f97d6e9fca8696a73ef4555e6af499a51
what this body honestly signs to9ead717843f51731dca42e0c91d77ea9135024f4d6e49fc58737574a6781a12c

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.