Proctoring that stands up to scrutiny.

Overview

There are two halves, and most customers use both for the same candidate.

They join on one identifier. You mint a session before the exam, pass its id to the SDK, and send the same session id when you submit the recording. That is what puts both halves in one report — and it is the step people most often miss.

What a finding is, and what it is not

The same caution applies, more weakly, to the recorded analysis: a looking-away interval means the model measured sustained gaze away from the screen, not that the candidate was reading something. That is why every finding carries a proof_frame — so a human can look at the image and decide.

Design your flow so a finding routes an interview to a reviewer, rather than failing a candidate on its own. Anything else is a decision you cannot defend if it is challenged.

Quickstart

A working integration is three calls. Everything else is detail.

1. Mint a session on your server

   This is the only endpoint you must build against. It returns a short-lived token scoped to one candidate and one page.

   Copy

   curl -X POST $INCPROC_BASE/api/v1/proctoring/browser/sessions \
     -H "X-API-Key: $INCPROC_KEY" \
     -H "X-API-Secret: $INCPROC_SECRET" \
     -H "Content-Type: application/json" \
     -d '{
       "origin": "https://exams.yourcompany.com",
       "reference_id": "candidate-4821",
       "capabilities": ["events", "evidence"],
       "ttl_seconds": 7200
     }'

   const BASE = process.env.INCPROC_BASE   // given to you with your keys
   
   const res = await fetch(
     `${BASE}/api/v1/proctoring/browser/sessions`,
     {
       method: 'POST',
       headers: {
         'X-API-Key': process.env.INCPROC_KEY,
         'X-API-Secret': process.env.INCPROC_SECRET,
         'Content-Type': 'application/json',
       },
       body: JSON.stringify({
         origin: 'https://exams.yourcompany.com',
         reference_id: 'candidate-4821',
         capabilities: ['events', 'evidence'],
         ttl_seconds: 7200,
       }),
     }
   )
   
   const { data } = await res.json()
   // Hand data.session_id + data.session_token to the browser. Nothing else.

   import os, requests
   
   BASE = os.environ["INCPROC_BASE"]   # given to you with your keys
   
   res = requests.post(
       f"{BASE}/api/v1/proctoring/browser/sessions",
       headers={
           "X-API-Key": os.environ["INCPROC_KEY"],
           "X-API-Secret": os.environ["INCPROC_SECRET"],
       },
       json={
           "origin": "https://exams.yourcompany.com",
           "reference_id": "candidate-4821",
           "capabilities": ["events", "evidence"],
           "ttl_seconds": 7200,
       },
       timeout=30,
   )
   session = res.json()["data"]

   $base = getenv('INCPROC_BASE');   // given to you with your keys
   
   $ch = curl_init($base . '/api/v1/proctoring/browser/sessions');
   curl_setopt_array($ch, [
       CURLOPT_POST           => true,
       CURLOPT_RETURNTRANSFER => true,
       CURLOPT_HTTPHEADER     => [
           'X-API-Key: ' . getenv('INCPROC_KEY'),
           'X-API-Secret: ' . getenv('INCPROC_SECRET'),
           'Content-Type: application/json',
       ],
       CURLOPT_POSTFIELDS => json_encode([
           'origin'       => 'https://exams.yourcompany.com',
           'reference_id' => 'candidate-4821',
           'capabilities' => ['events', 'evidence'],
           'ttl_seconds'  => 7200,
       ]),
   ]);
   $session = json_decode(curl_exec($ch), true)['data'];

   var body = """
       {"origin":"https://exams.yourcompany.com",
        "reference_id":"candidate-4821",
        "capabilities":["events","evidence"],
        "ttl_seconds":7200}
       """;
   
   var request = HttpRequest.newBuilder()
       .uri(URI.create(System.getenv("INCPROC_BASE")
           + "/api/v1/proctoring/browser/sessions"))
       .header("X-API-Key", System.getenv("INCPROC_KEY"))
       .header("X-API-Secret", System.getenv("INCPROC_SECRET"))
       .header("Content-Type", "application/json")
       .POST(HttpRequest.BodyPublishers.ofString(body))
       .build();
   
   var response = HttpClient.newHttpClient()
       .send(request, HttpResponse.BodyHandlers.ofString());

   origin must exactly match the page the exam is served from. The token is bound to it and refused anywhere else — and the 401 the browser gets does not explain why. https://exams.yourcompany.com and https://exams.yourcompany.com/ are the same; http:// and a different subdomain are not.

   If your account is restricted to specific domains, mint fails with 422 until the origin is on that list. The message says so:

   {
     "error": {
       "code": "VALIDATION_FAILED",
       "message": "Origin https://exams.yourcompany.com is not permitted to host a
                   proctoring session on this deployment. Contact support to have
                   it added."
     }
   }

   This is opt-in per account, not a gate everyone passes through. Most accounts have no restriction and any origin works from the moment your keys are issued. If yours has one — worth asking for, since it means a leaked key cannot mint sessions from somebody else's page and spend your balance — then every domain you mint from has to be registered first, including staging and preview URLs.

   Ask your account manager which applies to you before you start, and send the full list of domains at once. It is the one thing that can stop the very first call working, and the error is the only place it is visible.

2. Start the SDK in the candidate's browser

   Pass the minted session straight through. The SDK handles token refresh, batching and reconnection on its own.

   Copy

   npm install @incproctor/proctoring-sdk

   import { createProctoringSession } from '@incproctor/proctoring-sdk'
   
   // `session` is exactly what your server received in step 1.
   const proctoring = createProctoringSession({
     baseUrl: INCPROC_BASE,   // the same base URL your server uses
     session,
     camera:   { enabled: true, required: false },
     evidence: { enabled: true, intervalSec: 15, sources: ['camera'], maxDimension: 640 },
   })
   
   await proctoring.start()
   
   // When the candidate clicks "Finish" — this is what closes the session cleanly.
   await proctoring.stop()

   <script src="https://cdn.jsdelivr.net/npm/@incproctor/proctoring-sdk"></script>
   <script>
     const proctoring = InCruiterProctoring.createProctoringSession({
       baseUrl: INCPROC_BASE,
       session: MINTED_SESSION,
       camera: { enabled: true, required: false },
     })
     proctoring.start()
   </script>

   Never put your API key or secret in the browser. That credential reads every report your account has ever produced. Only the minted session_token belongs client-side — it expires, and it only works for one candidate on one origin.

3. Submit the recording when the interview ends

   Send the same session_id from step 1. That is what merges the live signals and the recorded analysis into one report.

   Copy

   curl -X POST $INCPROC_BASE/api/v1/proctoring/video/analyze \
     -H "X-API-Key: $INCPROC_KEY" \
     -H "X-API-Secret: $INCPROC_SECRET" \
     -H "Content-Type: application/json" \
     -d '{
       "file_url":      "https://your-storage/recordings/abc.mp4",
       "start_time":    "2026-09-14T10:00:00",
       "end_time":      "2026-09-14T10:45:00",
       "room_id":       "room-4821",
       "interview_id":  "interview-4821",
       "session_id":    "pbs_XXXXXXXXXXXXXXXX",
       "call_back_url": "https://yourcompany.com/hooks/proctoring"
     }'

   await fetch(`${BASE}/api/v1/proctoring/video/analyze`, {
     method: 'POST',
     headers: {
       'X-API-Key': process.env.INCPROC_KEY,
       'X-API-Secret': process.env.INCPROC_SECRET,
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({
       file_url:      recordingUrl,       // must be reachable by us
       start_time:    '2026-09-14T10:00:00',
       end_time:      '2026-09-14T10:45:00',
       room_id:       'room-4821',
       interview_id:  'interview-4821',
       session_id:    session.session_id, // ← the id from step 1
       call_back_url: 'https://yourcompany.com/hooks/proctoring',
     }),
   })

   requests.post(
       f"{BASE}/api/v1/proctoring/video/analyze",
       headers={
           "X-API-Key": os.environ["INCPROC_KEY"],
           "X-API-Secret": os.environ["INCPROC_SECRET"],
       },
       json={
           "file_url":      recording_url,
           "start_time":    "2026-09-14T10:00:00",
           "end_time":      "2026-09-14T10:45:00",
           "room_id":       "room-4821",
           "interview_id":  "interview-4821",
           "session_id":    session["session_id"],   # the id from step 1
           "call_back_url": "https://yourcompany.com/hooks/proctoring",
       },
       timeout=30,
   )

   We call your call_back_url when the report is ready. Do not poll — see Webhooks.

Authentication

Base URL

Every example on this page reads the base URL from INCPROC_BASE. There is one per environment, and your account manager gives it to you with your keys. Keep it in configuration rather than hardcoding it — the value differs between your test and production deployments, and a literal in the source is how test traffic ends up in production.

export INCPROC_BASE="https://…"        # from your account manager
export INCPROC_KEY="pk_…"
export INCPROC_SECRET="sk_…"

Your keys

You receive a key pair when your account is set up. There is nothing to request and nothing to configure — the pair arrives with your base URL, from your InCruiter account manager.

Every server-to-server call carries both, as headers.

You are given a separate pair per environment. A key issued for one will not work against another — that separation is deliberate, and it is what stops a test integration reaching production data.

Live browser proctoring

Once start() is called, the SDK reports these on its own. You do not wire them up.

Ending the session

Call stop() when the candidate finishes. It flushes anything queued and closes the session. If the tab simply closes, we detect it and close the session ourselves — but the explicit call is cleaner and settles the credit sooner.

Recorded interview analysis

Submit a finished recording and we return findings grouped into three kinds, each with a proof frame — the actual image the finding was made from.

Required fields

Fetching the report

When the webhook tells you a job is completed, fetch it with your API key:

curl "$INCPROC_BASE/api/v1/proctoring/video/results/$JOB_ID" \
  -H "X-API-Key: $INCPROC_KEY" -H "X-API-Secret: $INCPROC_SECRET"

What comes back

Findings are grouped by kind. Each interval carries the window, the proof frame, and how strong the signal was.

{
  "roomId": "room-4821",
  "frames": [ /* per-frame analysis, one entry per sampled frame */ ],
  "proctoring_summary": {
    "looking_away_intervals": [
      {
        "start": "2026-09-14T10:04:12",
        "end":   "2026-09-14T10:04:19",
        "proof_frame":     "data:image/jpeg;base64,…",   // or an https URL
        "proof_timestamp": "2026-09-14T10:04:15",
        "evidence_score":  0.7412
      }
    ],
    "face_issue_intervals": [ /* no face, multiple faces, partial face */ ],
    "device_intervals":     [ /* phone or second screen in frame */ ]
  }
}

Webhooks

We call you when a report is ready. This is the part worth reading twice.

What we send

The body is deliberately thin — identifiers and a status, never candidate data. A webhook body lands in log stores that are read far more widely than a database.

POST https://yourcompany.com/hooks/proctoring

webhook-id:        msg_2f8a91c4e7
webhook-timestamp: 1789385412
webhook-signature: v1,K8xW2pQ...

{
  "jobId":       "ea62cfe5-0b75-44c4-badf-27da5d8aa95e",
  "sessionId":   "pbs_XXXXXXXXXXXXXXXX",
  "roomId":      "room-4821",
  "interviewId": "interview-4821",
  "status":      "completed"
}

Then fetch the full report with your API key, over a channel you control.

Every status you can receive

Branch on status. A handler written for only the happy path will sit waiting for a report that is never coming.

{
  "jobId":       "ea62cfe5-0b75-44c4-badf-27da5d8aa95e",
  "sessionId":   "pbs_XXXXXXXXXXXXXXXX",
  "roomId":      "room-4821",
  "interviewId": "interview-4821",
  "status":      "failed",
  "reason":      "could not download the recording"
}

Verifying the signature

We follow the Standard Webhooks specification. Verify every request before you act on it — the endpoint is public, and anyone can POST to it.

The signed string is exactly {webhook-id}.{webhook-timestamp}.{raw body}.

import crypto from 'node:crypto'

export function verify(rawBody, headers, secret) {
  const id   = headers['webhook-id']
  const ts   = headers['webhook-timestamp']
  const sigs = headers['webhook-signature']
  if (!id || !ts || !sigs) return false

  // Reject anything older than 5 minutes — this is what stops a captured
  // request being replayed at you later.
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false

  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64')
  const expected = 'v1,' + crypto
    .createHmac('sha256', key)
    .update(`${id}.${ts}.${rawBody}`)   // rawBody — NOT JSON.stringify(parsed)
    .digest('base64')

  // The header may carry several space-separated signatures during a rotation.
  return sigs.split(' ').some((candidate) =>
    crypto.timingSafeEqual(
      crypto.createHash('sha256').update(candidate).digest(),
      crypto.createHash('sha256').update(expected).digest()
    )
  )
}

import base64, hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    wid = headers.get("webhook-id")
    ts  = headers.get("webhook-timestamp")
    sigs = headers.get("webhook-signature")
    if not (wid and ts and sigs):
        return False

    # Reject anything older than 5 minutes.
    if abs(time.time() - int(ts)) > 300:
        return False

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{wid}.{ts}.{raw_body.decode()}".encode()
    expected = "v1," + base64.b64encode(
        hmac.new(key, signed, hashlib.sha256).digest()
    ).decode()

    return any(hmac.compare_digest(c, expected) for c in sigs.split(" "))

function verify(string $rawBody, array $headers, string $secret): bool {
    $id  = $headers['webhook-id']        ?? null;
    $ts  = $headers['webhook-timestamp'] ?? null;
    $sig = $headers['webhook-signature'] ?? null;
    if (!$id || !$ts || !$sig) return false;

    if (abs(time() - (int) $ts) > 300) return false;

    $key = base64_decode(preg_replace('/^whsec_/', '', $secret));
    $expected = 'v1,' . base64_encode(
        hash_hmac('sha256', "$id.$ts.$rawBody", $key, true)
    );

    foreach (explode(' ', $sig) as $candidate) {
        if (hash_equals($expected, $candidate)) return true;
    }
    return false;
}

boolean verify(String rawBody, Map<String, String> headers, String secret)
        throws Exception {
    String id = headers.get("webhook-id");
    String ts = headers.get("webhook-timestamp");
    String sigs = headers.get("webhook-signature");
    if (id == null || ts == null || sigs == null) return false;

    if (Math.abs(System.currentTimeMillis() / 1000 - Long.parseLong(ts)) > 300)
        return false;

    byte[] key = Base64.getDecoder()
        .decode(secret.replaceFirst("^whsec_", ""));
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(key, "HmacSHA256"));
    String expected = "v1," + Base64.getEncoder().encodeToString(
        mac.doFinal((id + "." + ts + "." + rawBody).getBytes(UTF_8)));

    for (String candidate : sigs.split(" ")) {
        if (MessageDigest.isEqual(
                expected.getBytes(UTF_8), candidate.getBytes(UTF_8))) return true;
    }
    return false;
}

Responding

Return 2xx as soon as you have stored the message. Do the work afterwards — a slow handler looks like a failure and will be retried. Anything non-2xx is retried with exponential backoff.

Treat delivery as at-least-once: the same webhook-id can arrive twice. Store it and ignore repeats.

Credits & billing

One interview costs one credit — and only if it actually happened.

Why a hold, and not a charge-then-refund

Two reasons. A hold fails at the door: a client with one credit cannot start a thousand exams and find out a day later that the work is unbillable. And nothing appears on your statement for an interview that never completed — no 1000 → 999 → 1000.

Check your balance any time:

curl $INCPROC_BASE/api/v1/credits/me \
  -H "X-API-Key: $INCPROC_KEY" -H "X-API-Secret: $INCPROC_SECRET"

Errors

Every error carries a machine-readable code and a request_id. Log the request_id — quoting it to support is the difference between a minute and an afternoon.

{
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "X-API-Key and X-API-Secret are required."
  },
  "request_id": "req_491581f1a4034fb2a9a5e5dc306eff05"
}

Rate limits

Three separate ceilings. You will only ever design against the first.

A short burst above the limit is tolerated before 429 is returned. These are defaults; if your volume needs more, ask your account manager rather than working around them.

The two per-session limits exist so one candidate's browser cannot flood the account. The SDK queues and backs off on its own; you do not handle them.

Pagination

The list endpoints take a limit, newest first.

Versioning & changes

The REST API is versioned in the path: /api/v1/…. The browser SDK follows semantic versioning.

A breaking change means a new path version, and v1 would be supported alongside it for an agreed period — confirm the notice period in your contract; it is not set by this page.

For the SDK, pin a major version. A minor upgrade will not change the shape of anything you already use.

Limits & retention

Next