Skip to content
Jami3D
Developer docs menu

REST API: Webhooks

Every operation of this group with its parameters, body, answer and errors, as the OpenAPI document states them.

Events delivered to your endpoints: a signed JSON POST, retried at +1 min, +5 min, +30 min, +2 h, +6 h, +12 h, +24 h, +24 h, then dead. An endpoint failing for 3 days running is disabled and its owner told.

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.

Headers

NameInTypeDescription
Jami-SignatureRequiredheaderstring

t={unix seconds},v1={hex HMAC-SHA256 of t + "." + the body}, keyed by the endpoint's secret; two v1 entries while a rotated secret is in its grace. Refuse a t more than 300 s from your clock.

Jami-Event-IdRequiredheaderstring

The event's id: the same on every attempt and redelivery. Deduplicate on it.

Jami-Event-TypeRequiredheaderstring

The event's type.

Jami-Delivery-AttemptRequiredheaderstring

Which attempt this is: 1, then 2, 3… for the retries.

Payload

FieldTypeDescription
idRequiredstring (uuid)

The event's id: the same on every attempt and redelivery (Jami-Event-Id).

typeRequired"release.published"
versionRequired1
createdAtRequiredstring (date-time)

An ISO 8601 instant.

dataRequiredobject
data.projectRequiredobject
data.project.idRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

data.project.titleRequiredstring
data.releaseRequiredobject
data.release.idRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

data.release.numberRequiredinteger1–9007199254740991
data.release.publishedAtRequiredstring (date-time)

An ISO 8601 instant.

data.previousReleaseIdstring (uuid)

The release that was live before it; absent for the project's first.

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.

Headers

NameInTypeDescription
Jami-SignatureRequiredheaderstring

t={unix seconds},v1={hex HMAC-SHA256 of t + "." + the body}, keyed by the endpoint's secret; two v1 entries while a rotated secret is in its grace. Refuse a t more than 300 s from your clock.

Jami-Event-IdRequiredheaderstring

The event's id: the same on every attempt and redelivery. Deduplicate on it.

Jami-Event-TypeRequiredheaderstring

The event's type.

Jami-Delivery-AttemptRequiredheaderstring

Which attempt this is: 1, then 2, 3… for the retries.

Payload

FieldTypeDescription
idRequiredstring (uuid)

The event's id: the same on every attempt and redelivery (Jami-Event-Id).

typeRequired"session.completed"
versionRequired1
createdAtRequiredstring (date-time)

An ISO 8601 instant.

dataRequiredobject
data.sessionRequiredobject

The viewer session an event is about.

data.session.idRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

data.session.projectIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

data.session.releaseIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

data.session.surfaceRequiredstring≥ 1 characters

Where it was minted: a value of V1_SURFACES, read open (the vocabulary grows).

data.session.testRequiredboolean

Minted with a test key: keep it out of real records.

data.session.apiKeyIdstring (uuid)

The key it was minted with; absent for the project owner's own pages and keyless embeds.

data.session.externalUserIdstring1–200 characters

A secure embed's learner, as the integrator named them (POST /v1/viewer-tokens).

data.epochRequiredinteger0–9007199254740991
data.completedAtRequiredstring (date-time)

An ISO 8601 instant.

data.startedAtRequiredstring (date-time)

When the story began (a viewing resumed within 24 h counts from its first session).

data.durationMsRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

data.beatsVisitedRequiredobject[]

The Beats the viewer reached — visited, completed or skipped — in story order.

data.beatsVisited[].beatIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

data.beatsVisited[].aliasRequiredstring
data.beatsVisited[].nameRequiredstring
data.beatsVisited[].sceneIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

data.beatsVisited[].requiredRequiredboolean
data.beatsVisited[].statusRequiredstring≥ 1 characters

completed, skipped, visited or notVisited.

data.beatsVisited[].turnsRequiredinteger0–9007199254740991
data.resultRequiredobject

The session's result as GET /v1/sessions/{id}/result gives it, who the viewer is aside.

data.result.epochRequiredinteger0–9007199254740991
data.result.completedRequiredboolean
data.result.beatsRequiredobject[]
data.result.beats[].beatIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

data.result.beats[].aliasRequiredstring
data.result.beats[].nameRequiredstring
data.result.beats[].sceneIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

data.result.beats[].requiredRequiredboolean
data.result.beats[].statusRequiredstring≥ 1 characters

completed, skipped, visited or notVisited.

data.result.beats[].turnsRequiredinteger0–9007199254740991
data.result.quizzesRequiredobject[]
data.result.quizzes[].quizIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

data.result.quizzes[].aliasRequiredstring
data.result.quizzes[].titlestring
data.result.quizzes[].statusRequiredstring≥ 1 characters

completed, inProgress, skipped or notStarted.

data.result.quizzes[].scoreRequirednumber≥ 0
data.result.quizzes[].maxScoreRequirednumber≥ 0
data.result.quizzes[].percentRequirednumber0–100

0–100, one decimal.

data.result.quizzes[].passedboolean

Against the quiz's pass mark, once the quiz is completed.

data.result.quizzes[].correctCountRequiredinteger0–9007199254740991
data.result.quizzes[].questionsRequiredobject[]
data.result.quizzes[].questions[].questionIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

data.result.quizzes[].questions[].keyRequiredstring
data.result.quizzes[].questions[].promptstring
data.result.quizzes[].questions[].answeredRequiredboolean
data.result.quizzes[].questions[].correctRequiredboolean
data.result.quizzes[].questions[].pointsRequirednumber≥ 0
data.result.quizzes[].questions[].maxPointsRequirednumber≥ 0
data.result.quizzes[].questions[].attemptsRequiredinteger0–9007199254740991
data.result.quizzes[].questions[].responseone of

A response to one question: a choice (single, image choice), a set of choices (multi), true or false, or a typed answer. The server trims and bounds text itself (grading refuses an answer over 500 characters), so the wire allows some slack rather than failing a whole request.

When kind is “choice”
data.result.quizzes[].questions[].response.choiceIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

When kind is “choices”
data.result.quizzes[].questions[].response.choiceIdsRequiredstring[]1–10 items
When kind is “boolean”
data.result.quizzes[].questions[].response.valueRequiredboolean
When kind is “text”
data.result.quizzes[].questions[].response.textRequiredstring≤ 2000 characters
data.result.quizzes[].questions[].responseTextstring

The response in words: the chosen choices' text, true / false, the typed answer.

data.result.quizzes[].questions[].respondentone of

Who answers a quiz: the viewer, or the viewer playing a cast member ("as Cat").

When kind is “viewer”
When kind is “character”
data.result.quizzes[].questions[].respondent.castIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

data.result.variablesRequiredobject[]
data.result.variables[].variableIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

data.result.variables[].aliasRequiredstring
data.result.variables[].typeRequiredstring≥ 1 characters
data.result.variables[].valueRequiredboolean | number | string

A story value: a boolean, a number, or a short text (a choice is its key).

data.result.itemsRequiredobject[]
data.result.items[].resultIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

data.result.items[].aliasRequiredstring
data.result.items[].labelRequiredstring
data.result.items[].kindRequiredstring≥ 1 characters

quiz, score or flag.

data.result.items[].valueRequirednumber | boolean
data.result.totalsRequiredobject
data.result.totals.scoreRequirednumber≥ 0
data.result.totals.maxScoreRequirednumber≥ 0
data.result.totals.percentRequirednumber0–100
data.result.totals.passedboolean
data.result.totals.correctCountRequiredinteger0–9007199254740991
data.result.totals.questionCountRequiredinteger0–9007199254740991
data.result.totals.answeredCountRequiredinteger0–9007199254740991
data.result.totals.beatsCompletedRequiredinteger0–9007199254740991
data.result.totals.beatsTotalRequiredinteger0–9007199254740991
data.result.totals.completionRequirednumber0–1

Completed Beats ÷ all Beats (1 when there are none).

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.

Headers

NameInTypeDescription
Jami-SignatureRequiredheaderstring

t={unix seconds},v1={hex HMAC-SHA256 of t + "." + the body}, keyed by the endpoint's secret; two v1 entries while a rotated secret is in its grace. Refuse a t more than 300 s from your clock.

Jami-Event-IdRequiredheaderstring

The event's id: the same on every attempt and redelivery. Deduplicate on it.

Jami-Event-TypeRequiredheaderstring

The event's type.

Jami-Delivery-AttemptRequiredheaderstring

Which attempt this is: 1, then 2, 3… for the retries.

Payload

FieldTypeDescription
idRequiredstring (uuid)

The event's id: the same on every attempt and redelivery (Jami-Event-Id).

typeRequired"result.quiz_answered"
versionRequired1
createdAtRequiredstring (date-time)

An ISO 8601 instant.

dataRequiredobject
data.sessionRequiredobject

The viewer session an event is about.

data.session.idRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

data.session.projectIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

data.session.releaseIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

data.session.surfaceRequiredstring≥ 1 characters

Where it was minted: a value of V1_SURFACES, read open (the vocabulary grows).

data.session.testRequiredboolean

Minted with a test key: keep it out of real records.

data.session.apiKeyIdstring (uuid)

The key it was minted with; absent for the project owner's own pages and keyless embeds.

data.session.externalUserIdstring1–200 characters

A secure embed's learner, as the integrator named them (POST /v1/viewer-tokens).

data.epochRequiredinteger0–9007199254740991

The session's epoch when it was answered (a rewind starts the next: see result.retracted).

data.seqRequiredinteger1–9007199254740991

The answer's place in the session's story journal: a later answer has a higher number.

data.answeredAtRequiredstring (date-time)

An ISO 8601 instant.

data.anchorRequiredobject

Where in the story it was answered.

data.anchor.visitRequiredinteger1–9007199254740991
data.anchor.sceneIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

data.anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

data.quizIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

data.questionIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

data.respondentRequiredone of

Who answers a quiz: the viewer, or the viewer playing a cast member ("as Cat").

When kind is “viewer”
When kind is “character”
data.respondent.castIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

data.responseRequiredone of

A response to one question: a choice (single, image choice), a set of choices (multi), true or false, or a typed answer. The server trims and bounds text itself (grading refuses an answer over 500 characters), so the wire allows some slack rather than failing a whole request.

When kind is “choice”
data.response.choiceIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

When kind is “choices”
data.response.choiceIdsRequiredstring[]1–10 items
When kind is “boolean”
data.response.valueRequiredboolean
When kind is “text”
data.response.textRequiredstring≤ 2000 characters
data.responseTextstring

The response in words: the chosen choices' text, true / false, the typed answer.

data.attemptRequiredinteger1–9007199254740991
data.finalRequiredboolean

No later attempt can change this question's outcome.

data.correctRequiredboolean
data.pointsRequirednumber≥ 0
data.quizRequiredobject

The quiz after this answer.

data.quiz.quizIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

data.quiz.aliasRequiredstring
data.quiz.titlestring
data.quiz.statusRequiredstring≥ 1 characters

completed, inProgress, skipped or notStarted.

data.quiz.scoreRequirednumber≥ 0
data.quiz.maxScoreRequirednumber≥ 0
data.quiz.percentRequirednumber0–100

0–100, one decimal.

data.quiz.passedboolean

Against the quiz's pass mark, once the quiz is completed.

data.quiz.correctCountRequiredinteger0–9007199254740991
data.totalsRequiredobject

The whole session after this answer.

data.totals.scoreRequirednumber≥ 0
data.totals.maxScoreRequirednumber≥ 0
data.totals.percentRequirednumber0–100
data.totals.passedboolean
data.totals.correctCountRequiredinteger0–9007199254740991
data.totals.questionCountRequiredinteger0–9007199254740991
data.totals.answeredCountRequiredinteger0–9007199254740991
data.totals.beatsCompletedRequiredinteger0–9007199254740991
data.totals.beatsTotalRequiredinteger0–9007199254740991
data.totals.completionRequirednumber0–1

Completed Beats ÷ all Beats (1 when there are none).

result.retracted — A rewind erased answers

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

Headers

NameInTypeDescription
Jami-SignatureRequiredheaderstring

t={unix seconds},v1={hex HMAC-SHA256 of t + "." + the body}, keyed by the endpoint's secret; two v1 entries while a rotated secret is in its grace. Refuse a t more than 300 s from your clock.

Jami-Event-IdRequiredheaderstring

The event's id: the same on every attempt and redelivery. Deduplicate on it.

Jami-Event-TypeRequiredheaderstring

The event's type.

Jami-Delivery-AttemptRequiredheaderstring

Which attempt this is: 1, then 2, 3… for the retries.

Payload

FieldTypeDescription
idRequiredstring (uuid)

The event's id: the same on every attempt and redelivery (Jami-Event-Id).

typeRequired"result.retracted"
versionRequired1
createdAtRequiredstring (date-time)

An ISO 8601 instant.

dataRequiredobject
data.sessionRequiredobject

The viewer session an event is about.

data.session.idRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

data.session.projectIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

data.session.releaseIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

data.session.surfaceRequiredstring≥ 1 characters

Where it was minted: a value of V1_SURFACES, read open (the vocabulary grows).

data.session.testRequiredboolean

Minted with a test key: keep it out of real records.

data.session.apiKeyIdstring (uuid)

The key it was minted with; absent for the project owner's own pages and keyless embeds.

data.session.externalUserIdstring1–200 characters

A secure embed's learner, as the integrator named them (POST /v1/viewer-tokens).

data.epochRequiredinteger0–9007199254740991

The epoch the session goes on in: every answer listed was recorded in an earlier one.

data.quizIdsRequiredstring[]≥ 1 items

The quizzes some of whose answers the rewind erased.

data.answersRequiredobject[]≥ 1 items

Each answer erased.

data.answers[].quizIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

data.answers[].questionIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

data.answers[].seqRequiredinteger1–9007199254740991

The erased answer's seq, epoch and attempt, as its result.quiz_answered carried them.

data.answers[].epochRequiredinteger0–9007199254740991
data.answers[].attemptRequiredinteger1–9007199254740991
data.toRequiredobject

Where the story went back to: everything answered at or after it is gone.

data.to.visitRequiredinteger1–9007199254740991
data.to.sceneIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

data.to.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

data.rewoundAtRequiredstring (date-time)

An ISO 8601 instant.

data.totalsRequiredobject

The session after the erase.

data.totals.scoreRequirednumber≥ 0
data.totals.maxScoreRequirednumber≥ 0
data.totals.percentRequirednumber0–100
data.totals.passedboolean
data.totals.correctCountRequiredinteger0–9007199254740991
data.totals.questionCountRequiredinteger0–9007199254740991
data.totals.answeredCountRequiredinteger0–9007199254740991
data.totals.beatsCompletedRequiredinteger0–9007199254740991
data.totals.beatsTotalRequiredinteger0–9007199254740991
data.totals.completionRequirednumber0–1

Completed Beats ÷ all Beats (1 when there are none).

webhook.test — The dashboard's Send test

Sent by Send test on the dashboard, whatever the endpoint subscribes to. Not subscribable: only Send test delivers it.

Headers

NameInTypeDescription
Jami-SignatureRequiredheaderstring

t={unix seconds},v1={hex HMAC-SHA256 of t + "." + the body}, keyed by the endpoint's secret; two v1 entries while a rotated secret is in its grace. Refuse a t more than 300 s from your clock.

Jami-Event-IdRequiredheaderstring

The event's id: the same on every attempt and redelivery. Deduplicate on it.

Jami-Event-TypeRequiredheaderstring

The event's type.

Jami-Delivery-AttemptRequiredheaderstring

Which attempt this is: 1, then 2, 3… for the retries.

Payload

FieldTypeDescription
idRequiredstring (uuid)

The event's id: the same on every attempt and redelivery (Jami-Event-Id).

typeRequired"webhook.test"
versionRequired1
createdAtRequiredstring (date-time)

An ISO 8601 instant.

dataRequiredobject
data.endpointIdRequiredstring (uuid)

The endpoint the test was sent to.

data.messageRequiredstring