Event catalog

Each delivery is a JSON object with a common envelope. The event-specific fields live under data.

Common envelope

Field	Type	Description
`id`	string	Unique delivery ID, e.g. `dlv_01abc…`. Same value as the `X-Quippy-Delivery-Id` header. Use it to dedupe on retries.
`type`	string	The event type — e.g. `exam.completed`. Same as the `X-Quippy-Event` header.
`created`	ISO 8601 string	Timestamp of this delivery attempt.
`institutionId`	string	Your institution’s ID. Handy if you run one receiver for many tenants.
`test`	boolean (optional)	Present and `true` only for synthetic test deliveries.
`data`	object	Event-specific payload — see below.

IDs are opaque strings. The sample IDs below (usr_…, exm_…, ses_…) are illustrative — treat every ID as an opaque token and match it exactly. Do not parse, validate, or depend on any prefix or internal structure; the format can change without notice.

Partner API correlation. When an exam session was created through the Partner API — i.e. via POST /partner/v1/assignments, or by a student who signed in through your SSO — the exam.started, exam.completed, violation.detected, and grading.done events carry three extra data fields so you can correlate without a lookup:

Field	Meaning
`externalUserId`	Your own stable user id (the IdP `sub`) for this student. `null` if unknown.
`partnerAssignmentId`	The `assignmentId` returned by `POST /partner/v1/assignments`. `null` for non-assignment sessions.
`metadata`	The opaque object you passed at assignment time, echoed back. Absent when you sent none.

These fields are omitted (or null) for exam activity that didn’t originate from the Partner API.

Events

exam.started — fires when a student begins a proctored exam session

{
  "id": "dlv_01abc...",
  "type": "exam.started",
  "created": "2026-04-21T09:05:12.456Z",
  "institutionId": "inst_acme",
  "data": {
    "examId": "exm_01...",
    "sessionId": "ses_01...",
    "studentId": "usr_01...",
    "studentEmail": "jane@acme.com",
    "attempt": 1,
    "startedAt": "2026-04-21T09:05:12.012Z",
    "externalUserId": "your-sub-123",
    "partnerAssignmentId": "pas_01...",
    "metadata": { "cohort": "spring-2026" }
  }
}

Fires once per new proctoring session, immediately after the session document is persisted. studentId may be null for guest / link-based exam modes. attempt is 1-indexed — the student’s nth attempt at this exam. Great for driving real-time attendance dashboards. The externalUserId / partnerAssignmentId / metadata fields appear only for Partner API sessions.

exam.completed — fires when a student submits an exam

{
  "id": "dlv_01abc...",
  "type": "exam.completed",
  "created": "2026-04-20T10:15:30.123Z",
  "institutionId": "inst_acme",
  "data": {
    "examId": "exm_01...",
    "sessionId": "ses_01...",
    "studentId": "usr_01...",
    "studentEmail": "jane@acme.com",
    "score": {
      "percentage": 87,
      "totalScore": 87,
      "maxScore": 100,
      "correct": 26,
      "total": 30
    },
    "submittedAt": "2026-04-20T10:15:29.998Z",
    "externalUserId": "your-sub-123",
    "partnerAssignmentId": "pas_01...",
    "metadata": { "cohort": "spring-2026" }
  }
}

Fires once per submission, after the session is scored. studentId may be null for guest / link-based exam modes. The score here is the auto-marked portion; for exams that require manual or AI marking the final result arrives later via grading.done. The externalUserId / partnerAssignmentId / metadata fields appear only for Partner API sessions.

violation.detected — fires when a critical proctoring violation is recorded

{
  "id": "dlv_01abc...",
  "type": "violation.detected",
  "created": "2026-04-21T09:12:05.789Z",
  "institutionId": "inst_acme",
  "data": {
    "examId": "exm_01...",
    "sessionId": "ses_01...",
    "studentId": "usr_01...",
    "violationId": "vio_01...",
    "type": "multiple_faces",
    "severity": "critical",
    "message": "Multiple faces detected in frame",
    "riskScore": 30,
    "totalViolations": 2,
    "recordingTimestamp": 342,
    "recordingTimeFormatted": "00:05:42",
    "detectedAt": "2026-04-21T09:12:05.701Z",
    "externalUserId": "your-sub-123",
    "partnerAssignmentId": "pas_01...",
    "metadata": { "cohort": "spring-2026" }
  }
}

Only critical violations fire this event. Warnings (e.g. one quick head turn) are too noisy to push to customer systems by default — they’re visible inside Quippy’s own dashboard but don’t emit.

Fields:

Field	Meaning
`type`	The violation classifier — `multiple_faces`, `face_not_visible`, `tab_switch`, `copy_paste`, etc.
`severity`	Always `"critical"` for webhook deliveries.
`riskScore`	Cumulative session risk score (0–100), recalculated on each violation.
`totalViolations`	Count of all violations on this session so far, critical + warning combined.
`recordingTimestamp`	Seconds from recording start — useful to link directly into the playback. `null` if no recording.
`recordingTimeFormatted`	Same timestamp as `HH:MM:SS`.

grading.done — fires when an AI-graded assessment is persisted

{
  "id": "dlv_01abc...",
  "type": "grading.done",
  "created": "2026-04-21T09:20:44.321Z",
  "institutionId": "inst_acme",
  "data": {
    "assessmentId": "asm_01...",
    "userId": "usr_01...",
    "assessmentType": "cefr-speaking",
    "sessionId": "ses_01...",
    "assignmentId": null,
    "score": {
      "overall": 82,
      "pronunciation": 78,
      "fluency": 85,
      "accuracy": 80,
      "content": 84,
      "cefrLevel": "B2"
    },
    "language": "en-US",
    "completedAt": "2026-04-21T09:20:44.111Z",
    "externalUserId": "your-sub-123",
    "partnerAssignmentId": "pas_01...",
    "metadata": { "cohort": "spring-2026" }
  }
}

Fires once per new graded assessment across all grading entry points — `POST /api/grading/grade-open-ended`, `grade-pronunciation`, `grade-writing`, `cefr/speaking`, `ielts/speaking`, `ielts/writing`, `hskk/grade-speaking`, `dels-speaking/grade`, `dels-writing/grade`.score fields you’ll see depend on assessmentType:

Assessment type	Score fields populated
`speaking`, `open-ended`, `mixed`	`overall`, `pronunciation`, `fluency`, `accuracy`
`cefr-speaking`, `cefr-writing`	`overall`, `cefrLevel` (A1–C2)
`ielts-speaking`, `ielts-writing-task1`, `ielts-writing-task2`	`overall`, IELTS band in `overall` (0–9 scale)
`hskk_speaking`	`overall`, `pronunciation`, `fluency`
written	`overall`, `content`, `grammar` (under `score.*`)

Unpopulated score fields are null — don’t key off their presence.

Teacher edits to an existing assessment (reviewing, overriding a score) do not re-fire grading.done. The event is strictly “first grade was persisted.”

user.provisioned — fires when a new institution user is created

{
  "id": "dlv_01abc...",
  "type": "user.provisioned",
  "created": "2026-04-20T10:15:30.123Z",
  "institutionId": "inst_acme",
  "data": {
    "userId": "usr_01...",
    "email": "jane@acme.com",
    "displayName": "Jane Doe",
    "role": "member",
    "accessLevel": 2,
    "provisionedAt": "2026-04-20T10:15:29.998Z",
    "via": "sso"
  }
}

Fires when a new user is added to the institution. The via field tells you how it happened:

`via`	Fires on
`"invite"` (or omitted)	Admin invites a user via `POST /api/v2/users/invite` or the Members page
`"sso"`	A user authenticates via SSO for the first time (JIT provisioning) or a soft-deleted user is reactivated through SSO
`"scim"`	The customer’s IdP pushes a new user via `POST /api/scim/v2/Users`

role is one of admin, manager, editor, member, viewer. accessLevel is the numeric equivalent (5 / 4 / 3 / 2 / 1).

user.deprovisioned — fires when an institution user is removed

{
  "id": "dlv_01abc...",
  "type": "user.deprovisioned",
  "created": "2026-04-20T10:15:30.123Z",
  "institutionId": "inst_acme",
  "data": {
    "userId": "usr_01...",
    "email": "jane@acme.com",
    "displayName": "Jane Doe",
    "deactivatedAt": "2026-04-20T10:15:29.998Z",
    "via": "scim"
  }
}

Fires on soft-delete. via tells you the trigger:

`via`	Fires on
`"admin"` (or omitted)	An admin removes the user from the Members page
`"scim"`	The customer’s IdP deactivates the user (`active: false` PATCH or `DELETE /api/scim/v2/Users/:id`)

Pair with user.provisioned to drive user lifecycle syncs in external HRIS, CRM, or SIEM systems.

subscription.updated — fires when the Stripe subscription status changes

{
  "id": "dlv_01abc...",
  "type": "subscription.updated",
  "created": "2026-04-20T10:15:30.123Z",
  "institutionId": "inst_acme",
  "data": {
    "userId": "usr_01...",
    "stripeSubscriptionId": "sub_1Nx...",
    "status": "active",
    "cancelAtPeriodEnd": false,
    "currentPeriodEnd": "2026-05-20T10:15:29.000Z",
    "planId": "plan_pro_monthly"
  }
}

Fires when Stripe tells Quippy a subscription has changed — active, past_due, canceled, etc. planId may be null if the plan isn’t recorded on our side.

webhook.test — synthetic event from the 'Send test' button

{
  "id": "dlv_01abc...",
  "type": "webhook.test",
  "created": "2026-04-20T10:15:30.123Z",
  "test": true,
  "institutionId": "inst_acme",
  "data": {
    "message": "This is a synthetic test delivery from Quippy.",
    "at": "2026-04-20T10:15:30.000Z"
  }
}

Fires exactly once when you click Send test on an endpoint’s detail page. Test deliveries are not retried on failure — they’re a one-shot check.

Delivering to multiple endpoints

If you subscribe two endpoints to the same event, each gets its own delivery row with a distinct id — they don’t share attempts or retry state.

Getting Started

SSO

Webhooks

Partner API

API Reference

Common envelope

Events

Delivering to multiple endpoints

​Common envelope

​Events

​Delivering to multiple endpoints

Common envelope

Events

Delivering to multiple endpoints