Psychometric integration guide for vendors

Overview

Jobtrain provides a standard integration framework for psychometric testing providers to receive candidate invitations and submit assessment results securely and consistently across multiple Jobtrain clients.

This document outlines how your platform can integrate with Jobtrain using event-driven webhooks and a results submission API.

How the psychometric integration works

Stage	What happens	Who does it
1. Trigger	Jobtrain sends a webhook when a candidate reaches an "Assessment" stage.	Jobtrain
2. Assessment	You deliver the psychometric assessment to the candidate.	You
3. Result submission	You POST structured results to Jobtrain's standard endpoint.	You
4. Display	Results are displayed in the ATS interface and can drive status changes.	Jobtrain

Authentication

Until partner-level OAuth is introduced, vendors authenticate using Jobtrain’s existing client API authentication model. This uses a Jobtrain API user, client credentials, and API password to obtain a short-lived bearer token via POST /connect/token.

This is the same authentication flow used by all current Jobtrain API integrations and is enforced via standard client security roles.

This authentication mechanism will be replaced by partner-level OAuth in a future phase. Vendors will not be required to change webhook payloads or result submission formats when this change occurs.

How authentication works

• Jobtrain provisions a system user and API credentials inside each client's tenancy
• Jobtrain supplies these client-specific credentials to you securely during onboarding
• You store and use these credentials separately for each client

Authentication is performed via:

POST /connect/token

Using:

• clientId
• clientSecret
• username
• password (API password, not login password)

A bearer token is returned.

• Token lifetime ≈ 15 minutes
• Token is supplied as a bearer token on subsequent requests
• Permissions are enforced via the security role of the Jobtrain user used for the API

Authentication request example

POST /connect/token Content-Type: application/json { "clientId": "YOUR_CLIENT_ID", "clientSecret": "YOUR_CLIENT_SECRET", "username": "YOUR_USERNAME", "password": "YOUR_PASSWORD" }

An access_token must be used in all subsequent API requests (e.g. result submission).

Vendors are responsible for securely storing client credentials and must generate new bearer tokens as required. Credentials must not be shared or embedded in client-side code.

Receiving candidate invitations (Webhooks)

Choosing a webhook authentication method

Webhook authentication is configurable per provider, and only one method is used per integration. During onboarding, the vendor should confirm which authentication method will be used and Jobtrain will configure the selected method as part of the provider setup. 

Method	Via
HMAC signature validation (recommended)	X-JT-Signature
HTTP Basic Authentication	Authorisation header

Method 1 – HMAC Signature (recommended)

Jobtrain signs outbound webhook payloads using an HMAC SHA-256 signature.

Header example:

X-JT-Signature: sha256=<hmac>

The signature is computed using HMAC-SHA256 over the raw request body using the shared secret and included in the X-JT-Signature header.

The HMAC must be computed over the exact raw request body (byte-for-byte, UTF-8 encoded).

No JSON parsing, formatting, or whitespace changes should be applied prior to hashing.

Vendors must:

• Recalculate the HMAC signature using the shared secret
• Compare it with the X-JT-Signature header
• Reject the request if the signatures do not match

This ensures the webhook originated from Jobtrain and the payload was not altered.

Method 2 – HTTP Basic Authentication

Alternatively, vendors may request that Jobtrain authenticates webhook requests using HTTP Basic Authentication.

In this model:

• The vendor provides a username and password to Jobtrain during onboarding
• Jobtrain includes these credentials in the Authorization header when sending webhook requests

Example header:

Authorization: Basic base64(username:password)

Important behaviour:

• The username is defined by the vendor
• The password is defined by the vendor
• The password will differ per client tenancy
• Vendors must securely manage and store these credentials

This approach may be preferred where vendor infrastructure expects Basic Authentication rather than HMAC signature validation.  

 Rules for webhook events

• A single webhook endpoint is configured per partner and reused across all enabled clients.
• Event types are predefined by Jobtrain and derived from the integration type. You cannot define, add or customise event types.
• References to scopes describe Jobtrain's internal permission model. You do not request or configure scopes directly.
• You must not poll or query Jobtrain to determine candidate status, and you handle only the data explicitly sent to you

 Example: candidate.invite_assessment webhook 

You provide a secure HTTPS URL, for example https://yourdomain.com/jobtrain-events. Jobtrain delivers a POST request with the structure below.

Webhook headers

Only the authentication mechanism agreed during onboarding is present on the request.

Header	Value
X-JT-Event	candidate.invite_assessment
X-JT-Provider	your_provider_id
X-JT-Signature (if HMAC authentication is used)	sha256=<hmac>
Authorization (if Basic Authentication is configured)	Basic <base64>

What you must do:

• Validate the HMAC signature
• Acknowledge with HTTP 200–299 within 5 seconds
• De-duplicate using the idempotencyKey

Submitting results to Jobtrain

When the assessment is complete, submit the results using:

POST /integrations/assessment-results

The required scope is assessment.write

Scope is enforced through the client API user's security role permissions. You do not manage scopes directly.

Request body example

{

"clientId": <guid>,

"applicationId": <long>,

"candidateId": <long>,

"jobId": <long>,

"providerOrderRef": <string>,

"status": <string>,

"overall": {

"score": <int>,

"percentile": <int>,

"band": <string>

},

"results": [

{

"assessmentId": <string>,

"name": "<string>,

"overall": {

"score": <int>,

"percentile": <int>,

"band": <string>

},

"dimensions": [

{

"id": <string>,

"score": <decimal>

},

{

"id": <string>,

"score": <decimal>

}

]

}

],

"artifacts": [

{

"type": <string>,

"name": <string>,

"url":<string>

}

],

"providerRaw": {

"sessionId": <Guid>,

"packageCode": <string>

}

}

Key fields

Field	Purpose
clientId and applicationId	Tie the result to the right candidate.
overall	Contains the summary scoring for the package.
results[]	Allows multiple assessments in one package.
artifacts[]	Can include signed PDFs or other reports.

Submitting multiple result blocks does not create multiple assessment stages and does not automatically progress a candidate.

Retry and delivery behaviour

• Webhooks are retried on failure (up to 5 times)
• You must not poll Jobtrain or call GET endpoints
• You only handle the data explicitly sent to you

Your responsibilities

• Host a secure HTTPS webhook endpoint
• Respond to Jobtrain webhooks within 5 seconds
• Validate webhook authenticity using either HMAC signature validation or HTTP Basic Authentication
• De-duplicate events using the idempotencyKey
• Return structured results to Jobtrain
• Ensure uptime and traceability for webhook handling

Security and audit

• All actions are scoped to the client using a secure integration user
• Jobtrain logs all requests and responses for audit and support

Testing and go-live

Once development is complete:

• Jobtrain will test webhook delivery to your endpoint
• You’ll test your assessment flow and result submission
• Jobtrain will enable the integration per client via internal controls

Updating credentials

Client API credentials are issued per client during onboarding. If credentials need to be reissued, for example as part of a security rotation, Jobtrain Support provides the updated values and you update your integration configuration accordingly.

FAQs

Can I request multiple assessments in one webhook?

No. Each webhook event relates to a single assessment package for one application.

Can I test result submission before live rollout?

Yes. Jobtrain provides test credentials and sample application IDs for end-to-end testing in a UAT environment.

Can we use one set of credentials for all clients?

Not at present. You must store and use separate credentials per client, and a bearer token obtained for one client cannot be used for another. In a future phase, Jobtrain will introduce partner-level OAuth authentication. 

What changes when partner-level OAuth arrives?

You will authenticate once using partner credentials (an OAuth client ID and secret) to obtain an access token. Each request will identify the target client, and Jobtrain will authorise the request only for clients your integration is enabled for, resolving it internally to the correct tenancy under a Jobtrain-managed integration user. Webhook payloads and result submission formats will not change.