Wat moet een assessmenttool bouwen voor een koppeling met Workable of Carerix?

Een assessmentaanbieder die wil koppelen met Workable of Carerix bouwt vijf onderdelen. Veilige authenticatie met API-tokens, een vaste mapping tussen kandidaat- en vacature-ID's, uitnodigingen die automatisch vertrekken zodra een kandidaat de assessmentfase in gaat, resultaten die terugkomen op het kandidaatprofiel in het ATS, en ondertekende, idempotente webhooks. Daaromheen moet de gegevensverwerking voldoen aan de AVG en, zodra er AI in de scoring zit, aan de EU AI Act.

Dit artikel is een technisch naslagwerk voor de developers die de koppelingslaag bouwen. Het gaat over authenticatie, ID-mapping, het starten van uitnodigingen, het synchroniseren van resultaten, webhookbeveiliging en gegevensverwerking volgens de AVG. Waarom een goede ATS-koppeling voor skilltests zo veel uitmaakt voor recruiters, lees je in een apart artikel.

Welk ATS je ook kiest, de levenscyclus van een koppeling is steeds dezelfde.

1. Inrichten. Credentials uitwisselen en per ATS-fase een assessmenttemplate koppelen
2. Uitnodigen. Een fasewijziging in het ATS stuurt de kandidaat een assessmentuitnodiging
3. Afronden. De kandidaat maakt het assessment op het platform van de aanbieder
4. Resultaten terugsturen. De aanbieder pusht de resultaten, of het ATS haalt ze op via polling
5. Terugschrijven. Scores en status komen op het kandidaatrecord in het ATS

Het ATS is de bron van waarheid voor alle kandidaat- en vacaturegegevens. Jouw platform beheert alleen de status van de assessmentsessie en kopieert geen kandidaatprofielen.

Wat je vooraf geregeld moet hebben

Controleer deze punten voordat je een regel code schrijft.

• Een publiek bereikbaar HTTPS-endpoint voor inkomende webhooks (geen self-signed certificaten in productie)
• Duurzame opslag waarin je de Workable candidate_id, job_id en je eigen invitation_id bewaart en bij elk binnenkomend event kunt opzoeken
• Een ontwerp voor toestemming. Kandidaten geven expliciet toestemming voordat persoonsgegevens naar jouw platform gaan, en opnieuw voordat resultaten worden teruggedeeld
• Een vastgelegd bewaarbeleid volgens artikel 5, lid 1, onder e van de AVG, dat bepaalt hoe lang assessmentdata na een aannamebesluit bij jou blijft staan
• Aanmelding bij het Workable Partner Program (Assessment Provider-track) of het Carerix Integration Partner Program, voordat je productiecalls doet

Authenticatie en API-tokens

Workable

De Assessment Provider API van Workable werkt met een statisch access token in de HTTP-header Authorization. Volgens de developerdocumentatie 'Assessment Providers' van Workable (workable.readme.io) wordt elke call van Workable naar jouw endpoint op deze manier geauthenticeerd.

Authorization: Bearer <your_access_token>

Je krijgt dit token zodra je koppeling via het partnerprogramma van Workable is ingericht. Vervang het token minstens elke 90 dagen, en direct bij een vermoeden van misbruik. Bewaar het in een secrets manager (AWS Secrets Manager, HashiCorp Vault of vergelijkbaar) en niet in omgevingsvariabelen op gedeelde servers.

Valideer het token aan jouw kant bij elk request, nog voordat je een payload verwerkt. Geef 401 Unauthorized terug bij een ontbrekend of ongeldig token. De foutafhandeling van Workable verwacht statuscodes als 400, 401, 409 en 422 met een gestructureerde foutmelding.

{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The provided bearer token is not recognized."
  }
}

Carerix

Carerix bouwt koppelingen via een officieel partnerprogramma en stelt voor goedgekeurde partners een GraphQL API beschikbaar. Het precieze authenticatiemodel (OAuth 2.0 client credentials of een API-key) wordt bevestigd tijdens de partneronboarding. Bouw je een nieuwe connector, begin dan bij de pagina 'Become an Integration Partner' van Carerix. Daar staan het aanmeldproces en de verwachte doorlooptijd.

Ga er in de praktijk van uit dat je GraphQL-mutations gebruikt om te schrijven (een assessmentuitnodiging aanmaken, een kandidaat bijwerken) en queries om te lezen (kandidaat- of vacaturegegevens ophalen). Al het verkeer loopt minimaal via TLS 1.2.

Tokenbeveiliging bij beide ATS'en

• Vraag zo min mogelijk rechten aan. Laat de API scopes toe, kies dan alleen het lezen van kandidaten en fases en het schrijven van resultaten
• Log nooit het volledige token. Toon in diagnostische output alleen de laatste 4 tekens
• Controleer de echtheid van callbacks met een gedeeld geheim of een HMAC-handtekening (zie het hoofdstuk over webhooks)

Veldmapping van kandidaat- en vacature-ID's

Een strakke mapping voorkomt verweesde assessmentsessies en dubbele uitnodigingen. Deze ID-paren moet je opslag altijd bijhouden.

Veldmapping in Workable

Voor de uitnodiging heb je alleen de velden nodig om het assessment te versturen, namelijk first_name, last_name, email en language. Stuur velden als cover_letter, resume_url, cv-tekst of antwoorden op eigen screeningsvragen niet door, tenzij je koppeling ze echt nodig heeft en de kandidaat voor dat delen toestemming heeft gegeven.

Veldmapping in Carerix

In het GraphQL-schema van Carerix heten de vergelijkbare objecten Candidate en Vacancy. Map ze zo.

• Candidate.id naar je applicant_id
• Vacancy.id naar je role_id
• Een eigen veld of tag op het Candidate-object voor de invitation_id die jouw platform teruggeeft

Carerix gebruikt GUID's in tekstvorm als objectidentificatie. Laat de exacte veldnamen bevestigen tijdens de partneronboarding, want het GraphQL-schema verandert mee met platformupdates.

Zo min mogelijk persoonsgegevens onderweg

Stuur alleen wat nodig is. Voor de uitnodiging is email vereist, met optioneel first_name en preferred_language. Al het andere (geboortedatum, adres, nationaliteit, antwoorden op eigen vragenlijsten) blijft in het ATS. Jouw platform slaat die velden nooit op, ook niet als ze in de inkomende payload staan.

Assessments starten vanuit een fasewijziging in het ATS

Fasewijzigingen herkennen in Workable

Workable ondersteunt abonnementen op kandidaatevents via het endpoint /subscriptions. Je registreert een webhook met filters op fasewijzigingen. Met de subscription args filter je op eventtype, zodat je alleen candidate_moved of een vergelijkbaar event voor faseovergangen ontvangt en niet elke kandidaatactiviteit.

Gaat een kandidaat naar de ingestelde assessmentfase, dan stuurt Workable een POST naar je geregistreerde callback-URL. De payload bevat minimaal dit.

{
  "event_type": "candidate_moved",
  "event_id": "evt_01HXYZ",
  "candidate": {
    "id": "cand_7890",
    "name": "Alex van der Berg",
    "email": "[email protected]"
  },
  "job": {
    "id": "job_4567",
    "shortcode": "DEV001"
  },
  "stage": {
    "name": "Assessment",
    "previous_name": "Phone Screen"
  }
}

Bij dit event zoekt je service het assessmenttemplate op dat aan job.shortcode hangt, maakt een uitnodiging aan en slaat de invitation_id op bij candidate.id + job.id. Antwoord binnen 5 seconden met 200 OK en doe het zware werk asynchroon.

Verplichte parameters bij het aanmaken van een uitnodiging

Je call voor het aanmaken van een uitnodiging accepteert minimaal deze velden.

• applicant_id (gemapt vanaf het kandidaat-ID in het ATS)
• role_id (gemapt vanaf het vacature-ID in het ATS)
• email
• language (standaard en als de taal onbekend is)
• assessment_template_id (bepaald via je configuratie van fase naar template)

Deze optionele parameters wil je per klant kunnen instellen.

• allow_retake (boolean, standaard false)
• proctoring_enabled (boolean)
• expiry_hours (integer, bijvoorbeeld 72)

Heruitnodigingen en annuleringen

Wordt de kandidaat uit de assessmentfase teruggezet of afgewezen, dan doet je koppeling drie dingen.

1. Controleren of er een open invitation_id bestaat voor het paar candidate_id + job_id
2. De uitnodiging annuleren of laten verlopen via de interne API van je platform
3. De annulering loggen met een tijdstempel

Komt de kandidaat later opnieuw in die fase, maak dan een nieuwe invitation_id aan en archiveer de oude. Hergebruik nooit een uitnodigings-ID. Dwing dat af met een unique constraint in de database.

Assessmentresultaten ontvangen

Push of pull

Ondersteun zo mogelijk beide. Push (jouw platform stuurt resultaten met een POST naar een callback die bij Workable is geregistreerd) heeft de voorkeur omdat het sneller is, maar sommige ATS-inrichtingen werken met polling. Volgens de Assessment Providers-documentatie van Workable kunnen resultaten via een callback of via polling binnenkomen.

De resultaatpayload

Een standaard resultaatpayload van jouw platform bevat minimaal dit.

{
  "event_type": "assessment_completed",
  "event_id": "res_evt_9921",
  "invitation_id": "inv_3344",
  "attempt_id": "att_5566",
  "candidate_id": "cand_7890",
  "job_id": "job_4567",
  "status": "completed",
  "completed_at": "2026-09-09T14:33:00Z",
  "scores": {
    "overall": 72,
    "dimensions": {
      "cognitive_ability": 68,
      "conscientiousness": 81,
      "verbal_reasoning": 74
    }
  },
  "report_url": "https://app.assessmentplatform.com/reports/att_5566"
}

Gebruik voor het veld status een vaste woordenlijst, namelijk completed, abandoned, expired en failed. Het ATS vertaalt die naar eigen labels. Je contract mag nooit leunen op vrije tekst als status.

Resultaten terugschrijven naar het ATS

Voor Workable stuur je de resultaatpayload met een POST naar de callback-URL die bij het aanmaken van het assessment is meegegeven, of via het resultatenendpoint van de Assessment Provider API. Workable toont de scores daarna op het kandidaatprofiel. Zo werkt het ook bij aanbieders als Test Partnership, waarvan de resultaten op het Workable-profiel van de kandidaat verschijnen.

Voor Carerix werk je het kandidaatrecord bij met een GraphQL-mutation, via een eigen assessmentveld of een gestructureerde notitie met de scores en de rapport-URL.

Webhooks instellen en beveiligen

Abonnementen registreren in Workable

Registreer je callback-URL via het endpoint /subscriptions van Workable. Volgens de webhookdocumentatie van Workable filteren de subscription args de eventstroom. Stel ze dus zo in dat je alleen events ontvangt die voor jouw koppeling relevant zijn, zoals fasewijzigingen bij vacatures waar je assessmenttemplate actief is.

Handtekeningen controleren

Elke webhook van jouw platform naar het ATS en elke callback van het ATS naar jouw endpoint moet ondertekend zijn. Gebruik daarvoor HMAC-SHA256.

import hmac
import hashlib

def verify_signature(payload_bytes: bytes, received_sig: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, received_sig)

Stuur een header X-Webhook-Timestamp mee en weiger payloads waarvan het tijdstempel ouder is dan 5 minuten. Zo voorkom je replay-aanvallen.

Retries en idempotentie

Workable en de meeste andere ATS'en proberen mislukte webhooks opnieuw af te leveren. Je endpoint moet daarom idempotent zijn. Hetzelfde event_id twee keer verwerken geeft dezelfde uitkomst, zonder bijeffecten zoals dubbele uitnodigingen of dubbel weggeschreven resultaten.

Zo pak je dat aan.

1. Schrijf bij ontvangst het event_id weg in een deduplicatietabel met een TTL van minstens 24 uur
2. Bestaat het event_id al, geef dan direct 200 OK terug zonder te verwerken
3. Mislukt een uitgaande levering (jouw platform pusht resultaten), gebruik dan exponential backoff. Begin bij 5 seconden, verdubbel tot maximaal 5 minuten en stop na 7 pogingen
4. Zijn alle pogingen op, zet het bericht dan in een dead-letter queue en alarmeer het operationele team

curl -X POST https://callback.workable.com/assessment-results \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: sha256=<hmac_value>" \
  -H "X-Webhook-Timestamp: 2026-09-09T14:33:01Z" \
  -d '{
    "invitation_id": "inv_3344",
    "candidate_id": "cand_7890",
    "status": "completed",
    "scores": { "overall": 72 }
  }'

Voorbeeldrequests en -responses

Beschikbare assessmenttemplates opvragen

curl -X GET https://api.assessmentplatform.com/v1/templates \
  -H "Authorization: Bearer <your_access_token>"

Het antwoord ziet er zo uit.

{
  "templates": [
    { "id": "tmpl_001", "name": "Cognitive + Personality Bundle", "language": "en" },
    { "id": "tmpl_002", "name": "Logistiek instapniveau NL", "language": "nl" }
  ]
}

Een uitnodiging aanmaken

curl -X POST https://api.assessmentplatform.com/v1/invitations \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "applicant_id": "cand_7890",
    "role_id": "job_4567",
    "template_id": "tmpl_001",
    "email": "[email protected]",
    "first_name": "Alex",
    "language": "en",
    "expiry_hours": 72
  }'

Het antwoord ziet er zo uit.

{
  "invitation_id": "inv_3344",
  "status": "pending",
  "invitation_url": "https://app.assessmentplatform.com/start/inv_3344",
  "expires_at": "2026-09-12T14:33:00Z"
}

Minimale webhookhandler in Node.js

const crypto = require("crypto");
const express = require("express");
const app = express();

app.use(express.raw({ type: "application/json" }));

app.post("/webhooks/ats", (req, res) => {
  const sig = req.headers["x-webhook-signature"];
  const ts = req.headers["x-webhook-timestamp"];

  const age = Date.now() - new Date(ts).getTime();
  if (age > 5 * 60 * 1000) return res.status(400).send("Timestamp too old");

  const expected = crypto
    .createHmac("sha256", process.env.WEBHOOK_SECRET)
    .update(req.body)
    .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.replace("sha256=", "")))) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.body);
  // Idempotency check, then enqueue for processing
  res.sendStatus(200);
});

Testchecklist en troubleshooting

Loop elk scenario door in een stagingomgeving voordat je productieverkeer aanzet.

Troubleshooting per HTTP-status

Staan mislukte leveringen na 24 uur nog in de dead-letter queue, dan heeft je beheeromgeving een knop nodig om ze per invitation_id handmatig opnieuw te versturen, plus een export van openstaande resultaatpayloads om ze zo nodig handmatig in te voeren.

Privacy, AVG en de EU AI Act

Niet meer data dan nodig

Om een uitnodiging aan te maken hoeven maar drie velden van het ATS naar je assessmentplatform, namelijk email, first_name (voor de aanhef) en preferred_language. Al het andere blijft in het ATS. Kan je platform niet zonder extra velden, leg dan eerst de grondslag vast volgens artikel 6 van de AVG voordat je die overdracht aanzet.

Sla geen ruwe cv-tekst, antwoorden op screeningsvragen of beoordelingsnotities van recruiters op. Die velden kunnen in de webhookpayloads van sommige ATS'en zitten. Filter ze eruit bij binnenkomst, voordat ze je database bereiken.

Momenten van toestemming

Leg twee toestemmingsmomenten vast in je audittrail, elk met een UTC-tijdstempel.

1. Voordat de uitnodigingsmail vertrekt. De kandidaat weet dat er een extern assessment komt en heeft geen bezwaar gemaakt, of heeft expliciet ingestemd. Dat hangt af van de grondslag die je klant gebruikt
2. Voordat resultaten terug naar het ATS gaan. De kandidaat weet dat de scores zichtbaar worden voor het wervingsteam

Leg naast het tijdstempel ook vast hoe de toestemming is gegeven, bijvoorbeeld via een toestemmingsveld in het ATS of een vinkje in het product.

Dataopslag en bewaartermijnen

Werk je voor werkgevers in de EU, sla de persoonsgegevens uit je koppeling dan binnen de EU op. Selection Lab slaat bijvoorbeeld alle persoonsgegevens op in Frankfurt en haalt met lokale taalmodellen persoonlijke informatie uit gespreksdata voordat die bij een scoringsmodel komt. Dat patroon is het kopiëren waard. Laat elk AI-onderdeel in de scoring waar technisch mogelijk werken met geanonimiseerde of gepseudonimiseerde input.

Stel bewaartermijnen per klant in en laat ze automatisch handhaven. Een redelijke standaard is 12 maanden na afronding van het assessment, waarna de gegevens worden verwijderd of geanonimiseerd. Klanten in gereguleerde sectoren willen soms een kortere termijn. Bouw de termijn daarom als instelbare parameter en niet als vaste waarde in de code.

EU AI Act en auditlogging

Gebruikt een onderdeel van je assessmentplatform een AI-model om scores of aanbevelingen te genereren, dan valt het in de regel onder de AI-systemen met een hoog risico uit bijlage III van de EU AI Act (werving en selectie). Dat vraagt om deze maatregelen.

• Elke scoring loggen met de modelversie, de geanonimiseerde inputkenmerken en de score
• Per scoredimensie een begrijpelijke uitleg die een recruiter of kandidaat kan opvragen
• Vastleggen dat het model vóór ingebruikname is getest op bias tussen groepen met beschermde kenmerken
• Een conformiteitslog bijhouden waar je functionaris gegevensbescherming bij kan

Selection Lab combineert daarom transparante scorerapporten per dimensie met uitlegbare AI-uitkomsten die recruiters direct in de kandidaatweergave van hun ATS bekijken. Die herleidbaarheid is wat compliance met de EU AI Act op koppelingsniveau concreet vraagt. Elke automatische score die een aannamebesluit beïnvloedt, moet van begin tot eind te controleren zijn.

Hoe lang de bouw duurt

Een volledige koppeling met authenticatie, ID-mapping, uitnodigingen vanuit fasewijzigingen, synchronisatie van resultaten, webhookbeveiliging en AVG-proof gegevensverwerking kost doorgaans 2 tot 10 weken. Dat hangt af van de complexiteit van de ATS-omgeving en het aantal assessmenttemplates dat je inricht. Plan daarbinnen minstens een week voor end-to-end testen tegen een staging-omgeving van het ATS, voordat je productieverkeer aanzet.

Wil je zien hoe de ATS-koppelingen van Selection Lab in de praktijk werken? Vraag een demo aan.

Veelgestelde vragen