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:
| Setting | Rules |
|---|---|
| Address | An 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. |
| Secret | At 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. |
| Kinds | Which 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:
| Header | What it carries |
|---|---|
X-Lumi-Signature | t=<unix seconds>,v1=<hex>: proof the message came from us. See Check the signature. |
X-Lumi-Event | The type, so you can route before reading the body. |
X-Lumi-Delivery | The 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
type | When | data |
|---|---|---|
session.completed | A 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.blocked | A 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_reached | The 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.alert | Your 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.test | Only 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:
rootVersionIdis the first recording of the chain. A recording that was never corrected carries its ownversionIdhere. Add up results byrootVersionIdto count a recording and all its corrected copies as one.derivedFromappears 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.
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:
- Read
tandv1from theX-Lumi-Signatureheader. - Refuse the message if
tis more than 300 seconds (five minutes) from your clock, in either direction. - Compute HMAC-SHA256 of the text
<t>.<raw body>with your secret, as lowercase hex. - 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
idyou 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:
| Action | What it does | Limits |
|---|---|---|
| Send a test message | Sends 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 again | On 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 again | Sends 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 handled | Sends 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:
| State | Meaning |
|---|---|
| Delivered | Your server answered 2xx. |
| Waiting | Queued, not tried yet. |
| Retrying | A try failed; another is due. |
| Sending again | You pressed Send again; the try is on its way. |
| Gave up | Six tries failed. Send it again, or mark it as handled. |
| Not sent | Its 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.