Collega Screenwell agli strumenti che usi già

Chiavi API

Webhook, l'API e il server MCP per gli script usano la chiave API del tuo account. La trovi nell'app in Impostazioni → API e webhook. I connettori di Claude e ChatGPT non hanno bisogno di una chiave: accedi con Screenwell invece.

• Hai una chiave primaria e una secondaria, così puoi passare a una nuova chiave senza interruzioni.
• Una chiave agisce come te: vede le tue posizioni e quelle del tuo team, e nient'altro.
• Tienila sul tuo server. Non inserirla mai in una pagina web o in un'app mobile.

Zapier

Collega Screenwell al tuo ATS, a Slack, Google Sheets e a oltre 7.000 app, senza scrivere codice. Ogni trigger parte nel momento in cui succede in Screenwell.

Configurazione

1. 1Copia la tua chiave API nell’app: Impostazioni → API e webhook.
2. 2Apri Screenwell su Zapier con il pulsante qui sotto e accetta l’invito.
3. 3Crea uno Zap, scegli Screenwell e incolla la chiave API quando Zapier la chiede.
4. 4Scegli un trigger o un’azione, provalo e attiva lo Zap.

Trigger

Interview Scored

Luna ha finito un colloquio e la scheda è pronta: punteggio, raccomandazione, riepilogo e link.

Candidate Moved to Stage

Un candidato ha cambiato fase. Facoltativamente solo per una fase, come Shortlist.

New Candidate

È stato aggiunto un candidato, nell’app, tramite API o dal link del colloquio.

New Job

È stata creata un’offerta.

Interview Completed

Un colloquio è finito, prima che la scheda sia pronta.

Azioni e ricerche

Add Candidate to Job

Nome, e-mail, telefono e un CV facoltativo.

Send Interview Invite

Invia il link del colloquio per e-mail. Trova il candidato per e-mail o lo aggiunge.

Schedule Meet/Teams Interview

Prenota Luna per un colloquio su Google Meet o Microsoft Teams.

Update Candidate Stage

Sposta in Nuovo, Invitato, Colloquio fatto, Shortlist, Assunto o Non adatto.

Create Job

Titolo, descrizione, azienda e lingua del colloquio.

Find Candidate

Per e-mail, facoltativamente in un’offerta.

Find Job

Per titolo.

Idee

• Nuova candidatura su Workable, Recruitee, Teamtailor o Greenhouse → Send Interview Invite
• Interview Scored → una nota e la fase successiva nel tuo ATS
• Interview Scored → un messaggio nel canale selezione su Slack
• Interview Scored → una nuova riga in Google Sheets

Webhook

Screenwell invia una richiesta POST firmata con corpo JSON al tuo URL quando succede qualcosa. Puntala al tuo ATS, a un catch hook di Zapier o a un tuo endpoint.

Configuralo

1. 1Nell'app, apri Impostazioni → API e webhook e aggiungi il tuo URL del webhook. Deve essere un indirizzo https pubblico.
2. 2Copia il secret di firma che compare dopo il primo salvataggio. Ti serve per verificare le firme.
3. 3Premi «Invia evento di test» per ricevere un esempio di interview.scored con test: true.

Puoi anche impostare l'URL con l'API: PUT /api/v1/settings/webhook {"webhookUrl": "https://…"}.

Eventi

interview.scored

Luna ha finito un colloquio e la scheda di valutazione è pronta: il punteggio su 100, la sua decisione e quanto ne è sicura, il suo ragionamento e un link alla scheda di valutazione.

candidate.stage_changed

Un candidato si è spostato tra le fasi della bacheca, con provenienza, destinazione e chi lo ha spostato: luna dopo il colloquio, oppure recruiter quando è stato qualcuno del tuo team.

Gli account che usavano CV Parsing continuano a ricevere i suoi eventi precedenti (cv_parsed, candidate_created e altri).

Come si presenta una consegna

Ogni consegna ha la stessa busta: id, eventType, timestamp, userId e data. Gli eventi di test portano anche 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"
  }
}

Header

X-Screenwell-Event

Il tipo di evento, ad es. interview.scored.

X-Screenwell-Event-Id

L'id dell'evento. Resta lo stesso a ogni tentativo, quindi usalo per saltare gli eventi che hai già gestito.

X-Screenwell-Signature

t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, con chiave il tuo secret di firma.

Verifica la firma

1. 1Leggi il corpo grezzo della richiesta, prima di qualsiasi parsing JSON.
2. 2Calcola l'HMAC-SHA256 di «<t>.<raw body>» con il tuo secret di firma, in esadecimale.
3. 3Confrontalo con v1 in tempo costante, e rifiuta le richieste il cui t ha più di 5 minuti.

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

Nuovi tentativi

Rispondi con un qualsiasi stato 2xx entro 10 secondi. Se il tuo endpoint fallisce o non risponde, Screenwell riprova dopo 1 minuto, 5 minuti, 30 minuti e 2 ore. Impostazioni → API e webhook mostra le consegne più recenti con il loro stato e la risposta del tuo endpoint.

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

API REST

Un'API JSON per le posizioni, i candidati e i colloqui del tuo account. Invia la tua chiave nell'header X-API-KEY. Le risposte hanno questa forma: {"status": "success", "data": …}.

URL di base

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

Autenticazione

X-API-KEY: <API key>

Stati del candidato

Le fasi della bacheca corrispondono a questi stati: Nuovo = applied, Invitato = interview_scheduled, Intervistato = interviewed, In shortlist = selected, Assunto = hired, Non idoneo = rejected. Cambiare uno stato non invia mai un'email al candidato.

Esempio: aggiungi un candidato da un 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"}'

Server MCP

Lavora con Screenwell da Claude, ChatGPT, Cursor o un qualsiasi client MCP: «Chi ha messo in shortlist Luna questa settimana?», «Aggiungi questi 5 CV alla posizione Backend», «Invia a Tomas il link del colloquio». L'assistente agisce come te, con lo stesso accesso che hai nell'app.

Endpoint

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

Authorization

Bearer <token di accesso o chiave API>

Da claude.ai o ChatGPT: accedi con Screenwell

Nessuna chiave da copiare. Aggiungi Screenwell come connettore con l'URL del server, poi accedi con il tuo account Screenwell e approva l'accesso.

La pagina di Screenwell mostra quale app te lo sta chiedendo, l'indirizzo a cui ti riporta, e l'accesso che richiede: solo lettura, oppure lettura e azione (aggiungere, spostare e scrivere via email ai candidati, sempre dopo il tuo sì).

Ogni app collegata è elencata in Impostazioni → API e webhook → App collegate. Scollega la blocca alla richiesta successiva.

Con una chiave API: Claude Code, Cursor e script

Gli strumenti che permettono di impostare un header possono usare la tua chiave API. Claude Code può anche accedere: aggiungi il server senza header, poi esegui /mcp e scegli 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 si collega tramite mcp-remote, che aggiunge l'header della chiave al posto tuo.

Cursor, VS Code, MCP Inspector e gli script funzionano con lo stesso URL, usando un header con la chiave API oppure accedendo con il tuo account.

Con una chiave API, aggiungi l'header X-Screenwell-Scope: read per una connessione di sola lettura. L'assistente potrà così consultare le informazioni, ma non aggiungere, spostare o scrivere a nessuno.

Strumenti