Webhooks

Webhooks send a POST to your endpoint when session or evaluation-set events occur in your organization. Create, edit, and delete them in the dashboard Webhooks page. There is no public HTTP API for managing webhooks.

Setup

1. Open Webhooks in the dashboard.
2. Create a webhook with an HTTPS URL and at least one event type.
3. Edit the URL, name, or subscribed events later and delete the webhook when you no longer need it.

Prefer HTTPS. Skillflare does not currently sign webhook payloads; confirm an event by fetching the session with your organization API key.

Event types

A subscribed endpoint receives a separate POST per event type it is subscribed to. SESSION.STARTED fires when recording begins. DROPPED_OUT (no recording within 30 minutes of "I am ready") and EXPIRED (a PENDING session past expires_at) do not emit these events.

Request

Skillflare sends JSON with a 10 second timeout.

Headers

Body

{
  "id": "delivery-uuid",
  "type": "SESSION.STARTED",
  "created_at": "2026-08-17T19:00:00.000Z",
  "data": {
    "session": {
      "id": "uuid",
      "created_at": "2026-08-17T18:00:00.000Z",
      "session_status": "RECORDING",
      "recording_started_at": "2026-08-17T19:00:00.000Z",
      "challenge_id": "uuid",
      "latest_evaluation_set_id": null,
      "candidate_id": "uuid",
      "candidate_full_name": "Alex Example",
      "candidate_email": "alex@example.com",
      "candidate_meta": { "external_id": "ats-123" }
    }
  }
}

data.session is a public subset of the session, not the Sessions API resource. candidate_full_name and candidate_email come from the linked candidate (profile when linked, otherwise invite fields; either may be null). candidate_meta is the opaque JSON object stored as meta on the organization–candidate link (set on create or update; defaults to {}). Use data.session.id with GET /v1/sessions/:id for evaluation scores. Omit x-organization-id on that request to read the organization that owns the API key. A partner key may pass a direct child.

Delivery and retries

A retryable failure retries the whole dispatch. An endpoint that already returned 2xx may receive the same event again. Treat deliveries as idempotent: key on event type plus data.session.id. Do not key on X-Webhook-Delivery-Id or body id alone — retries mint a new UUID.

Receiving events

• Return 2xx quickly; do heavy work asynchronously.
• Prefer HTTPS.
• Confirm the session with your org API key rather than trusting the payload alone.

curl https://api.skillflare.co/v1/sessions/SESSION_UUID \
  -H "x-api-key: sk_skillflare_YOUR_KEY"