Skip to content
Jami3D
Developer docs menu

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.

ValueDescription
empty

Nothing was typed.

too_long

Longer than V1_WEBHOOK_URL_MAX_LENGTH.

not_a_url

Not an absolute https:// URL with a host.

https_required

http://: deliveries go over TLS only.

credentials

A user name or password in the URL: authenticate with the signature instead.

fragment

A #fragment, which is never sent.

blocked_address

A host that is (or always resolves to) an address deliveries never reach.

Events

EventWhenWho receives it
release.publishedA release of your project went live

Sent to the project's owner when one of its releases goes live for the first time.

session.completedA 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_answeredA 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.retractedA rewind erased answers

Sent to the account that minted the session when a rewind erases answers it was told about.

webhook.testSend test onlyThe 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.

A result.quiz_answered delivery
{
  "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.

app/webhooks/jami3d/route.ts
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 });
}
ValueDescription
missing

No Jami-Signature header.

malformed

A header that is not t=…,v1=….

timestamp

t is further from the receiver's clock than the tolerance: a replay, or a clock adrift.

mismatch

No v1 matches the body under this secret.

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:

  1. The first attempt, as the event happens.
  2. 1 minute after the previous attempt failed.
  3. 5 minutes after the previous attempt failed.
  4. 30 minutes after the previous attempt failed.
  5. 2 hours after the previous attempt failed.
  6. 6 hours after the previous attempt failed.
  7. 12 hours after the previous attempt failed.
  8. 24 hours after the previous attempt failed.
  9. 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.

ValueDescription
unspecified

0.0.0.0/8, ::.

loopback

127.0.0.0/8, ::1, and the localhost names.

private

10/8, 172.16/12, 192.168/16, fec0::/10, local-use NAT64 64:ff9b:1::/48.

cgnat

Carrier-grade NAT, 100.64.0.0/10.

link_local

169.254.0.0/16, fe80::/10.

metadata

Cloud metadata services: 169.254.169.254, 169.254.170.2, 168.63.129.16, 100.100.100.200, fd00:ec2::254.

ula

Unique local IPv6, fc00::/7.

multicast

224.0.0.0/4, ff00::/8.

documentation

192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 2001:db8::/32, 3fff::/20.

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, …