← Lumi for institutions GUIDES FOR YOUR TEAM

Webhooks: know when a student finishes a lesson

The messages we send your server when a student finishes a lesson or reaches a limit. How to check the signature, and how a failed message is tried again.

Last updated: 17 November 2026

A webhook is a message our server sends to yours when something happens: a student finished a lesson, hit a limit, or your organisation is close to its monthly limit. Webhooks are the dependable way to hear about lessons, including from apps, where the player’s browser messages cannot reach you.

Set it up

On the console’s Integration page, under Webhook, an owner or admin saves three things:

SettingRules
AddressAn https:// address on a public server, on the standard port (no :port). Addresses on localhost or a private network cannot receive our messages: to test from a laptop, use a public https tunnel. We do not follow redirects.
SecretAt least 16 characters. Generate makes one for you, starting whsec_. It is shown only while you save it; afterwards the console shows just its first characters. Save a new one to replace it.
KindsWhich kinds of message to send. Leave them all ticked to get every kind.

One address per environment: the sandbox console’s webhook gets sandbox messages, and the live console’s gets live ones. Sandbox lessons send real messages, so test your receiver there first.

What we send

Every message is an HTTPS POST with a JSON body:

{
  "id": "…",
  "type": "session.completed",
  "orgId": "…",
  "createdAt": "2026-10-21T10:42:07.000Z",
  "attempt": 1,
  "data": { "…": "the event's fields, below" }
}

and these headers:

HeaderWhat it carries
X-Lumi-Signaturet=<unix seconds>,v1=<hex>: proof the message came from us. See Check the signature.
X-Lumi-EventThe type, so you can route before reading the body.
X-Lumi-DeliveryThe message id. It stays the same on every retry and resend, so use it to ignore a message you have already handled.

attempt counts every try of this message so far.

The kinds of message

typeWhendata
session.completedA student finished a lesson. Sent once the player reports the end, or 10 minutes after the lesson finished if it never does.sessionId, userId (your id), entitlement, mode, lessonId, versionId and rootVersionId (library lessons), derivedFrom (a corrected recording), minutes, doubts (questions asked), completedEarly, completedAt
session.blockedA launch, a lesson start or a question during a lesson was refused. At most one per student, reason and day.userId, reason, at, and mode, lessonId and sessionId when known
learner.cap_reachedThe refusal was one of the student’s own limits: lessons_per_day, doubts_per_day or trial_exhausted. One per student, limit and day.userId, cap, at
usage.alertYour organisation is close to its monthly limit or has reached it (kind: "monthly_limit": at most one warning and one “reached” message a month, sent again if we raise the limit), or students went over your fair-use question count (kind: "fair_use", once a month).period, kind, at, and for monthly_limit: share, action, reached; for fair_use: limit, learnersOver, maxDoubtsPerLearner
webhook.testOnly when someone presses Send a test message.{ "test": true }

A library lesson names the recording the student watched with versionId. When your reviewers fix a recording without recording it again, the fixed copy is a new recording with its own versionId, so two more fields keep the two together:

  • rootVersionId is the first recording of the chain. A recording that was never corrected carries its own versionId here. Add up results by rootVersionId to count a recording and all its corrected copies as one.
  • derivedFrom appears only on a corrected recording: { "versionId": "…", "n": 2 }, the recording it corrects and its number on the Library page.

Making, approving or taking off a recording sends no message of its own, whether it is a first recording or a corrected one.

session.blocked carries the same codes as the player’s lumi.blocked, listed in Integration, plus org_suspended when a lesson start is refused because your organisation is suspended (the player says lessons_paused). Days are India-time days.

A monthly_limit alert says how far through the limit it is with share (0.8 is a warning at 80%, 1 is the limit itself), and what happens at the limit with action: alert (a warning only) or block (new lessons pause). It carries reached: true once lessons have actually been paused. Lessons already running always finish.

Let the test through

If your receiver refuses kinds it does not know, let webhook.test through and answer it with a 2xx, so the test button works.

Check the signature

Before you trust a message, check that it came from us:

  1. Read t and v1 from the X-Lumi-Signature header.
  2. Refuse the message if t is more than 300 seconds (five minutes) from your clock, in either direction.
  3. Compute HMAC-SHA256 of the text <t>.<raw body> with your secret, as lowercase hex.
  4. Accept the message only if it equals v1, comparing in constant time.

Use the raw body exactly as it arrived, before any JSON parsing: re-encoding the JSON changes the bytes and the signature no longer matches.

Node

import crypto from "node:crypto";

// rawBody: the request body exactly as received (a Buffer or a UTF-8 string), never re-serialised JSON
export function verifyLumiSignature(secret, header, rawBody, nowSeconds = Math.floor(Date.now() / 1000)) {
  if (!header) return false;
  const parts = new Map(header.split(",").map((p) => {
    const i = p.indexOf("=");
    return [p.slice(0, i).trim(), p.slice(i + 1).trim()];
  }));
  const t = parts.get("t");
  const v1 = parts.get("v1");
  if (!t || !v1 || !/^\d+$/.test(t)) return false;
  if (Math.abs(nowSeconds - Number(t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest();
  const given = Buffer.from(v1, "hex");
  return expected.length === given.length && crypto.timingSafeEqual(expected, given);
}

// Express: keep the raw body for this route
app.post("/lumi/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyLumiSignature(process.env.LUMI_WEBHOOK_SECRET, req.get("x-lumi-signature"), req.body)) {
    return res.sendStatus(400);
  }
  const message = JSON.parse(req.body.toString("utf8"));
  res.sendStatus(200);        // answer first, then do the work
  handleLumiMessage(message); // ignore a message.id you have already handled
});

Python

import hashlib
import hmac
import re
import time

def verify_lumi_signature(secret: str, header: str | None, raw_body: bytes, now: int | None = None) -> bool:
    if not header:
        return False
    parts = {}
    for part in header.split(","):
        i = part.find("=")
        parts[part[:i].strip()] = part[i + 1:].strip()
    t, v1 = parts.get("t"), parts.get("v1")
    if not t or not v1 or not re.fullmatch(r"[0-9]+", t):
        return False
    now = int(time.time()) if now is None else now
    if abs(now - int(t)) > 300:
        return False
    expected = hmac.new(secret.encode("utf-8"), t.encode("ascii") + b"." + raw_body, hashlib.sha256).digest()
    try:
        given = bytes.fromhex(v1)
    except ValueError:
        return False
    return len(given) == len(expected) and hmac.compare_digest(expected, given)

# Flask:   verify_lumi_signature(SECRET, request.headers.get("X-Lumi-Signature"), request.get_data())
# Django:  verify_lumi_signature(SECRET, request.headers.get("X-Lumi-Signature"), request.body)
# FastAPI: verify_lumi_signature(SECRET, request.headers.get("x-lumi-signature"), await request.body())

Keep your secret on your server, like an API key. If it leaks, save a new one in the console: messages are signed with the new secret from then on.

Answering, and what happens if you don’t

  • Answer with any 2xx within 10 seconds. That marks the message delivered. We never read your reply’s body, so an empty 200 is fine. Do slow work after you answer.
  • Anything else is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours. After the sixth failed try the message gives up.
  • Expect the same message twice now and then, for example when your answer was lost on the way back. Ignore a message whose id you have already handled.
  • A message whose kind you turned off, or whose address you removed, before it was sent is not sent, and never tried again.

Test, send again, mark as handled

All on the Integration page, under Messages sent, for owners and admins:

ActionWhat it doesLimits
Send a test messageSends one signed webhook.test to your saved address now, and shows the result: the status your server answered, how long it took, or why it could not be sent (timeout, connection failed, certificate problem, or an address that does not point to a public server). A pass ticks Connect your webhook on the Overview checklist.5 a minute, 30 a day
Send againOn a message that gave up: sends it once more, with the same id, signed with your current secret. If that try fails, it gives up again.10 a minute, 200 a day
Send these againSends again every message from the last 30 days that gave up and is not marked handled, oldest first, up to 25 per press.Once every two minutes
Mark as handledSends nothing. Takes a message that gave up out of the Overview alert, for one you have dealt with another way. It stays in the list with the mark.60 a minute

A message about a student who was erased is never sent again.

The message list

Messages sent lists every message except test messages, newest first, with its state:

StateMeaning
DeliveredYour server answered 2xx.
WaitingQueued, not tried yet.
RetryingA try failed; another is due.
Sending againYou pressed Send again; the try is on its way.
Gave upSix tries failed. Send it again, or mark it as handled.
Not sentIts kind was turned off, or the address removed, before it went.

Open a message to see exactly what was sent. Delivered and not-sent messages are kept for 90 days; messages that gave up are kept. The Overview’s Needs your attention list shows how many gave up in the last 30 days and are not yet handled.