Webhooks
Hear on your backend when a release goes live, a learner answers or finishes, or a rewind erases answers — signed, retried and deduplicable.
Add an endpoint
In Integration → Webhooks, add an https:// endpoint, choose its events and, if you like, the projects or keys it is about. Its signing secret (whsec_…) is shown once. Send test delivers a webhook.test event at once; the deliveries log shows every attempt and redelivers any of them.
| Value | Description |
|---|---|
empty | Nothing was typed. |
too_long | Longer than |
not_a_url | Not an absolute |
https_required |
|
credentials | A user name or password in the URL: authenticate with the signature instead. |
fragment | A |
blocked_address | A host that is (or always resolves to) an address deliveries never reach. |
Events
| Event | When | Who receives it |
|---|---|---|
release.published | A release of your project went live | Sent to the project's owner when one of its releases goes live for the first time. |
session.completed | A viewer finished the story | Sent to the account that minted the session: the owner of the publishable or secret key, or the project's owner for its own pages and keyless embeds. |
result.quiz_answered | A quiz answer was graded | Sent to the account that minted the session: the owner of the publishable or secret key, or the project's owner for its own pages and keyless embeds. |
result.retracted | A rewind erased answers | Sent to the account that minted the session when a rewind erases answers it was told about. |
webhook.testSend test only | The dashboard's Send test | Sent by Send test on the dashboard, whatever the endpoint subscribes to. Not subscribable: only Send test delivers it. |
Each delivery is one JSON event: {id, type, version, createdAt, data}. version is the payload's schema version; payloads only ever gain fields, and new event types are added over time — acknowledge a type you do not know. The REST reference has every field of every payload.
{
"id": "0199c4a0-0000-7000-8000-000000000103",
"type": "result.quiz_answered",
"version": 1,
"createdAt": "2026-10-03T09:20:31.250Z",
"data": {
"session": {
"id": "0199c4a0-0000-7000-8000-0000000000c1",
"projectId": "0199c4a0-0000-7000-8000-0000000000a1",
"releaseId": "0199c4a0-0000-7000-8000-0000000000b2",
"surface": "secure_embed",
"test": false,
"apiKeyId": "0199c4a0-0000-7000-8000-0000000000d1",
"externalUserId": "learner-42"
},
"epoch": 0,
"seq": 7,
"answeredAt": "2026-10-03T09:20:31.250Z",
"anchor": { "visit": 1, "sceneId": "0199c4a0-0000-7000-8000-0000000000e1", "ms": 41250 },
"quizId": "0199c4a0-0000-7000-8000-0000000000f1",
"questionId": "0199c4a0-0000-7000-8000-0000000000f2",
"respondent": { "kind": "character", "castId": "0199c4a0-0000-7000-8000-0000000000f3" },
"response": { "kind": "choice", "choiceId": "0199c4a0-0000-7000-8000-0000000000f4" },
"responseText": "From the sea",
"attempt": 1,
"final": true,
"correct": false,
"points": 0,
"quiz": {
"quizId": "0199c4a0-0000-7000-8000-0000000000f1",
"alias": "cat_book",
"title": "Where does rain come from?",
"status": "completed",
"score": 0,
"maxScore": 1,
"percent": 0,
"passed": false,
"correctCount": 0
},
"totals": {
"score": 0,
"maxScore": 1,
"percent": 0,
"passed": false,
"correctCount": 0,
"questionCount": 1,
"answeredCount": 1,
"beatsCompleted": 1,
"beatsTotal": 2,
"completion": 0.5
}
}
}Deliveries can arrive out of order and more than once. Deduplicate on the event's id (also the Jami-Event-Id header), and order a session's answers by seq. A rewind starts a new epoch and sends result.retracted for the answers it erased.
Verify the signature
Every delivery carries Jami-Signature: t={unix seconds},v1={hex}, where the hex is HMAC-SHA256 of t, a dot and the body exactly as sent, keyed by the endpoint's secret. Check it before you trust anything in the body, on the raw body — never on JSON you parsed and wrote again. While you rotate the secret, the header carries a v1 for the new secret and one for the old: one match is enough.
verifyWebhook from jami3d/webhooks does all of it with the runtime's WebCrypto (Node 20 and later, Deno, Bun, Cloudflare Workers): it compares in constant time, refuses a t more than 300 seconds from your clock, takes several secrets while you roll one out, and answers the parsed event.
import { verifyWebhook } from "jami3d/webhooks";
const seen = new Set<string>(); // keep this in your database: a delivery may come twice
/** POST /webhooks/jami3d — a Next.js route handler; Hono, Deno, Bun and Workers read the same. */
export async function POST(request: Request): Promise<Response> {
const delivery = await verifyWebhook(
await request.text(), // the body exactly as it arrived
request.headers.get("Jami-Signature"),
process.env.JAMI3D_WEBHOOK_SECRET ?? "",
);
if (!delivery.ok) return new Response(delivery.reason, { status: 400 });
const { event } = delivery;
if (seen.has(event.id)) return new Response(null, { status: 204 });
seen.add(event.id);
if (event.type === "result.quiz_answered") {
const { session, quizId, correct, points } = event.data;
console.log(session.externalUserId ?? session.id, quizId, correct, points);
}
// Any other type, including one added after this was written: acknowledge it.
return new Response(null, { status: 204 });
}| Value | Description |
|---|---|
missing | No |
malformed | A header that is not |
timestamp |
|
mismatch | No |
Retries and disabling
Any 2xx answer is a delivery. An answer takes at most 10 s, and only its first 4 KB is read; anything else — another status, a redirect, a timeout — is retried:
- The first attempt, as the event happens.
- 1 minute after the previous attempt failed.
- 5 minutes after the previous attempt failed.
- 30 minutes after the previous attempt failed.
- 2 hours after the previous attempt failed.
- 6 hours after the previous attempt failed.
- 12 hours after the previous attempt failed.
- 24 hours after the previous attempt failed.
- 24 hours after the previous attempt failed.
After 9 attempts the delivery is dead. Redeliver it from the deliveries log when your endpoint is back.
An endpoint that keeps failing for three days, with no success in between, is switched off and its owner told by email; switch it back on in Integration once it answers again. Deliveries for an endpoint whose plan no longer includes webhooks are held back and never sent.
Addresses deliveries never reach
A delivery goes to public addresses only. The address is checked when you save the endpoint and again on every connection, against the address the name resolves to then — a name that later points inside a private network is refused at that moment. Redirects are never followed.
| Value | Description |
|---|---|
unspecified | 0.0.0.0/8, |
loopback | 127.0.0.0/8, |
private | 10/8, 172.16/12, 192.168/16, |
cgnat | Carrier-grade NAT, 100.64.0.0/10. |
link_local | 169.254.0.0/16, |
metadata | Cloud metadata services: 169.254.169.254, 169.254.170.2, 168.63.129.16, 100.100.100.200, |
ula | Unique local IPv6, |
multicast | 224.0.0.0/4, |
documentation | 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, |
benchmarking | 198.18.0.0/15. |
reserved | Everything else that is no public unicast address: 240.0.0.0/4, 192.0.0.0/24, 6to4, Teredo, … |