Public API & webhooks

CLIP Learn exposes a small, read-only REST API and an outbound webhook system so you can pull your tenant's data into other tools (a data warehouse, a CRM, Zapier, a spreadsheet sync) and be notified when things happen (an assignment is marked, an essay result is released). Everything is scoped to a single tenant: an API key can only ever read the data of the tenant that created it, and a webhook only fires for events in its own tenant.

Both keys and webhooks are managed from Faculty → API & webhooks (/faculty/api). Only users with the FACULTY or ADMIN role can open that page or create, revoke, or delete keys and webhooks. There is no self-service API for creating data — every v1 endpoint is a GET.

Authentication

The API uses a bearer token in the Authorization header. There are no query-string keys, no cookies, and no OAuth.

Authorization: Bearer <your-key>

The server takes the key, hashes it with SHA-256, and looks it up. If the key is unknown, malformed, or has been revoked, the request is rejected. On every successful call the key's Last used timestamp is updated.

Minting and revoking API keys

Keys are created on the API & webhooks page under the API keys section.

Create a key

Key name field

Key format. A generated key looks like clip_ followed by a URL-safe base64 string, e.g. clip_qX8f2.... The prefix stored for display is the first 12 characters (clip_ plus the first seven characters of the random part).

The keys table

Each row in the API keys table shows:

If you have no keys yet, the table is hidden entirely and only the Generate key form and the Try it example are shown.

Revoke a key

Revocation is immediate and permanent — the row's action cell changes to revoked, and any request using that key from that moment on returns 401. There is no "un-revoke"; generate a new key instead. Revoking one key never affects any other key.

Endpoints

All three endpoints are GET, require a valid bearer key, run on the Node.js runtime, and are always dynamic (never cached). Each returns a JSON object with a single data array. Results are automatically filtered to the key's tenant — there is no tenant parameter to pass, and you cannot read another tenant's data.

GET /api/v1/courses

Returns every course belonging to the key's tenant, ordered by title (A→Z).

Response

{
  "data": [
    {
      "id": "clx...",
      "slug": "company-law",
      "title": "Company Law",
      "subtitle": "Foundations of UK company law",
      "published": true
    }
  ]
}

GET /api/v1/learners

Returns the tenant's learners — users with the CANDIDATE role who are members of the tenant. Ordered by name (A→Z), capped at 1000 rows.

Response

{
  "data": [
    {
      "id": "clx...",
      "name": "Amina Yusuf",
      "email": "amina@example.com",
      "createdAt": "2026-05-01T09:12:00.000Z"
    }
  ]
}

GET /api/v1/enrollments

Returns enrolments for all of the tenant's courses. Ordered by start date (most recent first), capped at 2000 rows.

Response

{
  "data": [
    {
      "userId": "clx...",
      "courseId": "clx...",
      "startedAt": "2026-06-10T00:00:00.000Z",
      "expiresAt": "2027-06-10T00:00:00.000Z"
    }
  ]
}

The response contains only ids and dates — join userId against /api/v1/learners and courseId against /api/v1/courses to get names and titles. The list is capped at 2000 enrolments with no pagination parameter.

Example request

curl https://cliplaw.academy/api/v1/courses \
  -H "Authorization: Bearer <your-key>"

The same header works for /api/v1/learners and /api/v1/enrollments.

Webhooks

Webhooks push a small JSON payload to a URL you control whenever a subscribed event happens in your tenant. They are managed on the same API & webhooks page, under the Webhooks section.

Add a webhook

Webhook form fields

Each webhook in the list shows its URL, its subscribed event, the first 12 characters of its signing secret, and — if any deliveries have failed — a failure count (for example 3 failures).

Delete a webhook

Deletion is immediate; the webhook stops receiving events at once. There is no per-webhook "pause" toggle in the UI — to stop deliveries, delete the webhook.

Events

Payload shape

Every delivery is an HTTP POST with a JSON body of this shape:

{
  "event": "assignment.graded",
  "at": "2026-07-12T14:03:00.000Z",
  "data": {
    "submissionId": "clx...",
    "userId": "clx...",
    "assignment": "Problem question — directors' duties",
    "score": 18,
    "maxScore": 25
  }
}

An exam.result delivery's data instead contains submissionId, userId, topic, marks, and maxMarks.

Request headers and signature

Each delivery carries these headers:

The signature is computed as HMAC_SHA256(secret, rawBody), hex-encoded, prefixed with sha256=. To verify a delivery, compute the same HMAC over the exact raw bytes you received (do not re-serialise the JSON) using the webhook's secret, and compare — ideally with a constant-time comparison.

Verification example (Node.js):

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected = "sha256=" +
    createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(signatureHeader);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Where secret is the full whsec_… value shown when you created the webhook, rawBody is the unparsed request body, and signatureHeader is the value of x-clip-signature.

Delivery behaviour

• Fan-out. When an event fires, it is delivered to every active webhook in the tenant that is subscribed to that event or to *. Deliveries happen in parallel.
• Fire-and-forget. Delivery never blocks or breaks the action that triggered it (grading still succeeds even if your endpoint is down). There are no automatic retries.
• Success vs failure. A 2xx response resets the webhook's failure count to zero. Any non-2xx response, a timeout, or a connection error increments its failure count, which is displayed next to the webhook.
• Timeout. Each delivery has a 6-second timeout; slow endpoints are treated as failures.
• SSRF protection. Delivery URLs are validated and IP-pinned. Requests that resolve to private, loopback, or otherwise internal address ranges are blocked, and redirects are not followed. Point your webhook at a publicly reachable HTTPS endpoint.

Permissions summary

Keys and webhooks are always tenant-scoped: they only ever read or fire for the tenant that owns them, and there is no cross-tenant access.

xAPI statements (LRS integration)

CLIP Learn exposes learner activity as xAPI (Experience API) statements, so a Learning Record Store can ingest it.

GET /api/v1/xapi/statements — newest first, authenticated with the same bearer key. Query parameters:

The response is { "statements": [ … ] }, where each statement follows the xAPI shape — an actor (the learner, as an account on this platform), a verb (viewed / completed / answered / asked / messaged), an object (the activity), and a timestamp. Internal events map to standard xAPI verb IRIs (e.g. a completed lesson → http://adlnet.gov/expapi/verbs/completed).

curl "https://cliplaw.academy/api/v1/xapi/statements?limit=50&since=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer <your-key>"

Statements are tenant-scoped to the key. (This is a read/pull surface; SCORM 2004 and a full LTI story are on the roadmap.)