Koppel Screenwell aan de tools die je al gebruikt

API-sleutels

Webhooks, de API en de MCP-server voor scripts gebruiken de API-sleutel van je account. Je vindt hem in de app onder Instellingen → API en webhooks. Voor connectors van Claude en ChatGPT heb je geen sleutel nodig: je logt in plaats daarvan in met Screenwell.

• Je hebt een primaire en een secundaire sleutel, zodat je zonder downtime kunt overstappen op een nieuwe sleutel.
• Een sleutel handelt namens jou: hij ziet je eigen vacatures en die van je team, en verder niets.
• Bewaar hem op je server. Zet hem nooit in een webpagina of mobiele app.

Zapier

Koppel Screenwell zonder code aan je ATS, Slack, Google Sheets en meer dan 7.000 andere apps. Elke trigger gaat af op het moment dat het in Screenwell gebeurt.

Instellen

1. 1Kopieer je API-sleutel in de app: Instellingen → API & webhooks.
2. 2Open Screenwell op Zapier met de knop hieronder en accepteer de uitnodiging.
3. 3Maak een Zap, kies Screenwell en plak je API-sleutel als Zapier erom vraagt.
4. 4Kies een trigger of actie, test hem en zet de Zap aan.

Triggers

Interview Scored

Luna heeft een gesprek afgerond en de scorecard is klaar: score, advies, samenvatting en link.

Candidate Moved to Stage

Een kandidaat is van fase gewisseld. Optioneel alleen voor één fase, zoals Shortlist.

New Candidate

Er is een kandidaat toegevoegd, in de app, via de API of via de gesprekslink.

New Job

Er is een vacature aangemaakt.

Interview Completed

Een gesprek is afgelopen, voordat de scorecard klaar is.

Acties en zoekopdrachten

Add Candidate to Job

Naam, e-mail, telefoon en optioneel een cv.

Send Interview Invite

Mailt de link naar het gesprek. Zoekt de kandidaat op e-mail of voegt hem toe.

Schedule Meet/Teams Interview

Plant Luna in een gesprek via Google Meet of Microsoft Teams.

Update Candidate Stage

Verplaatst naar Nieuw, Uitgenodigd, Gesprek gehad, Shortlist, Aangenomen of Geen match.

Create Job

Titel, omschrijving, bedrijf en taal van het gesprek.

Find Candidate

Op e-mail, optioneel binnen één vacature.

Find Job

Op titel.

Ideeën

• Nieuwe sollicitant in Workable, Recruitee, Teamtailor of Greenhouse → Send Interview Invite
• Interview Scored → notitie en volgende fase in je ATS
• Interview Scored → bericht in het recruitmentkanaal in Slack
• Interview Scored → een nieuwe rij in Google Sheets

Webhooks

Screenwell stuurt een ondertekende POST met een JSON-body naar je URL zodra er iets gebeurt. Richt hem op je ATS, een Zapier catch hook of je eigen endpoint.

Instellen

1. 1Open in de app Instellingen → API en webhooks en voeg je webhook-URL toe. Dit moet een openbaar https-adres zijn.
2. 2Kopieer de signing secret die verschijnt na de eerste keer opslaan. Je hebt hem nodig om signatures te controleren.
3. 3Druk op “Testevent sturen” om een voorbeeld van interview.scored te krijgen met test: true.

Je kunt de URL ook instellen via de API: PUT /api/v1/settings/webhook {"webhookUrl": "https://…"}.

Events

interview.scored

Luna heeft een interview afgerond en de scorecard is klaar: de score op 100, haar beslissing en hoe zeker ze is, haar onderbouwing en een link naar de scorecard.

candidate.stage_changed

Een kandidaat is verplaatst tussen fasen van het bord, met van waar, naar waar en wie de verplaatsing deed: luna na het interview, of recruiter wanneer iemand van je team dat deed.

Accounts die CV Parsing gebruikten, blijven de oudere events daarvan ontvangen (cv_parsed, candidate_created en andere).

Hoe een levering eruitziet

Elke levering heeft dezelfde envelop: id, eventType, timestamp, userId en data. Testevents bevatten ook test: true.

{
  "id": "evt_01J9ZK4T7Q2M8C6V",
  "eventType": "interview.scored",
  "timestamp": "2026-09-26T09:44:12.000Z",
  "userId": "usr_4f1c",
  "data": {
    "candidate": { "id": "cand_8f2c", "name": "Maya Kowalski", "email": "maya@example.com" },
    "job": { "id": "job_31a0", "title": "Senior Frontend Engineer" },
    "interview": { "id": "int_77b1", "finishedAt": "2026-09-26T09:43:50.000Z", "durationSeconds": 1920 },
    "score": 84,
    "decision": "hire",
    "confidence": 82,
    "summary": "Strong frontend engineer who led a design system migration.",
    "reasoning": "Explains her trade-offs clearly and meets 4 of 5 requirements.",
    "scorecardUrl": "https://<app-host>/interviews/int_77b1",
    "integrity": { "level": "none" }
  }
}

{
  "id": "evt_01J9ZK4VB1XK0D3R",
  "eventType": "candidate.stage_changed",
  "timestamp": "2026-09-26T09:44:13.000Z",
  "userId": "usr_4f1c",
  "data": {
    "candidate": { "id": "cand_8f2c", "name": "Maya Kowalski", "email": "maya@example.com" },
    "job": { "id": "job_31a0", "title": "Senior Frontend Engineer" },
    "from": "invited",
    "to": "shortlisted",
    "movedBy": "luna",
    "changedBy": "rule",
    "reason": "Moved by rule: score 84 ≥ 75",
    "at": "2026-09-26T09:44:13.000Z"
  }
}

Headers

X-Screenwell-Event

Het type event, bijv. interview.scored.

X-Screenwell-Event-Id

Het event-id. Dit blijft hetzelfde bij elke nieuwe poging, dus gebruik het om events die je al hebt verwerkt over te slaan.

X-Screenwell-Signature

t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, met een sleutel op basis van je signing secret.

Controleer de signature

1. 1Lees de raw request body, vóór enige JSON-parsing.
2. 2Bereken de HMAC-SHA256 van "<t>.<raw body>" met je signing secret, als hex.
3. 3Vergelijk dit met v1 in constante tijd, en wijs verzoeken af waarvan t meer dan 5 minuten oud is.

import crypto from 'node:crypto'
import express from 'express'

const app = express()
const SECRET = process.env.SCREENWELL_WEBHOOK_SECRET // whsec_...

// Keep the raw body: the signature is over the exact bytes we sent.
app.post('/webhooks/screenwell', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('X-Screenwell-Signature') ?? ''
  const { t, v1 } = Object.fromEntries(header.split(',').map((part) => part.split('=')))
  const expected = crypto.createHmac('sha256', SECRET).update(`${t}.${req.body}`).digest('hex')

  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 5 * 60
  const valid = v1?.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
  if (!fresh || !valid) return res.status(400).send('bad signature')

  const event = JSON.parse(req.body)
  // Skip events you have already handled: event.id stays the same on retries.
  console.log(event.eventType, event.data)
  res.sendStatus(200)
})

app.listen(3000)

import hashlib, hmac, json, os, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["SCREENWELL_WEBHOOK_SECRET"].encode()  # whsec_...

@app.post("/webhooks/screenwell")
def screenwell():
    header = request.headers.get("X-Screenwell-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t, v1 = parts.get("t", "0"), parts.get("v1", "")

    body = request.get_data()  # the raw bytes, before any JSON parsing
    expected = hmac.new(SECRET, f"{t}.".encode() + body, hashlib.sha256).hexdigest()

    if abs(time.time() - int(t)) > 300 or not hmac.compare_digest(v1, expected):
        abort(400)

    event = json.loads(body)
    # Skip events you have already handled: event["id"] stays the same on retries.
    print(event["eventType"], event["data"])
    return "", 200

Nieuwe pogingen

Antwoord met een 2xx-status binnen 10 seconden. Als je endpoint faalt of niet antwoordt, probeert Screenwell het opnieuw na 1 minuut, 5 minuten, 30 minuten en 2 uur. Instellingen → API en webhooks toont de laatste leveringen met hun status en het antwoord van je endpoint.

1. 0
2. +1m
3. +5m
4. +30m
5. +2h

REST API

Een JSON-API voor de vacatures, kandidaten en interviews in je account. Stuur je sleutel mee in de X-API-KEY-header. Antwoorden zien eruit als {"status": "success", "data": …}.

Basis-URL

https://api.screenwell.ai/api/v1

Authenticatie

X-API-KEY: <API key>

Kandidaatstatussen

De fasen van het bord komen overeen met deze statussen: Nieuw = applied, Uitgenodigd = interview_scheduled, Geïnterviewd = interviewed, Op shortlist = selected, Aangenomen = hired, Geen match = rejected. Een status wijzigen stuurt nooit een e-mail naar de kandidaat.

Voorbeeld: een kandidaat toevoegen via een cv

curl -X POST https://api.screenwell.ai/api/v1/jobs/job_31a0/candidates \
  -H "X-API-KEY: $SCREENWELL_API_KEY" \
  -F "file=@maya-kowalski-cv.pdf"

# or from a link
curl -X POST https://api.screenwell.ai/api/v1/jobs/job_31a0/candidates \
  -H "X-API-KEY: $SCREENWELL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileUrl": "https://example.com/cv/maya.pdf"}'

curl -X PUT https://api.screenwell.ai/api/v1/candidates/cand_8f2c/status \
  -H "X-API-KEY: $SCREENWELL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "selected"}'

MCP-server

Werk met Screenwell vanuit Claude, ChatGPT, Cursor of elke MCP-client: “Wie heeft Luna deze week op de shortlist gezet?”, “Voeg deze 5 cv's toe aan de Backend-rol”, “Stuur Tomas de interviewlink”. De assistent handelt namens jou, met dezelfde toegang die jij hebt in de app.

Endpoint

POST https://api.screenwell.ai/mcp

Authorization

Bearer <sign-in-token of API-sleutel>

Vanuit claude.ai of ChatGPT: log in met Screenwell

Geen sleutel om te kopiëren. Voeg Screenwell toe als connector met de server-URL, log dan in met je Screenwell-account en keur de toegang goed.

De Screenwell-pagina laat zien welke app het vraagt, het adres waar je naar teruggaat, en de toegang die wordt gevraagd: alleen lezen, of lezen en handelen (kandidaten toevoegen, verplaatsen en mailen, altijd na jouw ja).

Elke gekoppelde app staat in Instellingen → API en webhooks → Gekoppelde apps. Ontkoppelen sluit de toegang af bij het volgende verzoek.

Met een API-sleutel: Claude Code, Cursor en scripts

Tools waarmee je een header kunt instellen, kunnen in plaats daarvan je API-sleutel gebruiken. Claude Code kan ook inloggen: voeg de server toe zonder header, voer dan /mcp uit en kies Authenticate.

# sign in with Screenwell: add the server, then run /mcp and choose Authenticate
claude mcp add --transport http screenwell https://api.screenwell.ai/mcp

# or with an API key
claude mcp add --transport http screenwell https://api.screenwell.ai/mcp \
  --header "Authorization: Bearer <API key>"

# read-only
claude mcp add --transport http screenwell-read https://api.screenwell.ai/mcp \
  --header "Authorization: Bearer <API key>" \
  --header "X-Screenwell-Scope: read"

{
  "mcpServers": {
    "screenwell": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.screenwell.ai/mcp", "--header", "Authorization: Bearer ${SCREENWELL_KEY}"],
      "env": { "SCREENWELL_KEY": "<API key>" }
    }
  }
}

Claude Desktop maakt verbinding via mcp-remote, dat de key-header automatisch voor je toevoegt.

Cursor, VS Code, de MCP Inspector en scripts werken met dezelfde URL, met een API-sleutel als header of door in te loggen.

Voeg met een API-sleutel de header X-Screenwell-Scope: read toe voor een alleen-lezen verbinding. De assistent kan dan dingen opzoeken, maar niemand toevoegen, verplaatsen of mailen.

Tools