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
| Name | In | Type | Description |
|---|---|---|---|
Jami-SignatureRequired | header | string |
|
Jami-Event-IdRequired | header | string | The event's id: the same on every attempt and redelivery. Deduplicate on it. |
Jami-Event-TypeRequired | header | string | The event's |
Jami-Delivery-AttemptRequired | header | string | Which attempt this is: 1, then 2, 3… for the retries. |
Payload
| Field | Type | Description |
|---|---|---|
idRequired | string (uuid) | The event's id: the same on every attempt and redelivery ( |
typeRequired | "release.published" | |
versionRequired | 1 | |
createdAtRequired | string (date-time) | An ISO 8601 instant. |
dataRequired | object | |
data.projectRequired | object | |
data.project.idRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
data.project.titleRequired | string | |
data.releaseRequired | object | |
data.release.idRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
data.release.numberRequired | integer1–9007199254740991 | |
data.release.publishedAtRequired | string (date-time) | An ISO 8601 instant. |
data.previousReleaseId | string (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
| Name | In | Type | Description |
|---|---|---|---|
Jami-SignatureRequired | header | string |
|
Jami-Event-IdRequired | header | string | The event's id: the same on every attempt and redelivery. Deduplicate on it. |
Jami-Event-TypeRequired | header | string | The event's |
Jami-Delivery-AttemptRequired | header | string | Which attempt this is: 1, then 2, 3… for the retries. |
Payload
| Field | Type | Description |
|---|---|---|
idRequired | string (uuid) | The event's id: the same on every attempt and redelivery ( |
typeRequired | "session.completed" | |
versionRequired | 1 | |
createdAtRequired | string (date-time) | An ISO 8601 instant. |
dataRequired | object | |
data.sessionRequired | object | The viewer session an event is about. |
data.session.idRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
data.session.projectIdRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
data.session.releaseIdRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
data.session.surfaceRequired | string≥ 1 characters | Where it was minted: a value of |
data.session.testRequired | boolean | Minted with a test key: keep it out of real records. |
data.session.apiKeyId | string (uuid) | The key it was minted with; absent for the project owner's own pages and keyless embeds. |
data.session.externalUserId | string1–200 characters | A secure embed's learner, as the integrator named them ( |
data.epochRequired | integer0–9007199254740991 | |
data.completedAtRequired | string (date-time) | An ISO 8601 instant. |
data.startedAtRequired | string (date-time) | When the story began (a viewing resumed within 24 h counts from its first session). |
data.durationMsRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
data.beatsVisitedRequired | object[] | The Beats the viewer reached — visited, completed or skipped — in story order. |
data.beatsVisited[].beatIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
data.beatsVisited[].aliasRequired | string | |
data.beatsVisited[].nameRequired | string | |
data.beatsVisited[].sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
data.beatsVisited[].requiredRequired | boolean | |
data.beatsVisited[].statusRequired | string≥ 1 characters |
|
data.beatsVisited[].turnsRequired | integer0–9007199254740991 | |
data.resultRequired | object | The session's result as |
data.result.epochRequired | integer0–9007199254740991 | |
data.result.completedRequired | boolean | |
data.result.beatsRequired | object[] | |
data.result.beats[].beatIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
data.result.beats[].aliasRequired | string | |
data.result.beats[].nameRequired | string | |
data.result.beats[].sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
data.result.beats[].requiredRequired | boolean | |
data.result.beats[].statusRequired | string≥ 1 characters |
|
data.result.beats[].turnsRequired | integer0–9007199254740991 | |
data.result.quizzesRequired | object[] | |
data.result.quizzes[].quizIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
data.result.quizzes[].aliasRequired | string | |
data.result.quizzes[].title | string | |
data.result.quizzes[].statusRequired | string≥ 1 characters |
|
data.result.quizzes[].scoreRequired | number≥ 0 | |
data.result.quizzes[].maxScoreRequired | number≥ 0 | |
data.result.quizzes[].percentRequired | number0–100 | 0–100, one decimal. |
data.result.quizzes[].passed | boolean | Against the quiz's pass mark, once the quiz is completed. |
data.result.quizzes[].correctCountRequired | integer0–9007199254740991 | |
data.result.quizzes[].questionsRequired | object[] | |
data.result.quizzes[].questions[].questionIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
data.result.quizzes[].questions[].keyRequired | string | |
data.result.quizzes[].questions[].prompt | string | |
data.result.quizzes[].questions[].answeredRequired | boolean | |
data.result.quizzes[].questions[].correctRequired | boolean | |
data.result.quizzes[].questions[].pointsRequired | number≥ 0 | |
data.result.quizzes[].questions[].maxPointsRequired | number≥ 0 | |
data.result.quizzes[].questions[].attemptsRequired | integer0–9007199254740991 | |
data.result.quizzes[].questions[].response | one 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.choiceIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “choices” | ||
data.result.quizzes[].questions[].response.choiceIdsRequired | string[]1–10 items | |
| When kind is “boolean” | ||
data.result.quizzes[].questions[].response.valueRequired | boolean | |
| When kind is “text” | ||
data.result.quizzes[].questions[].response.textRequired | string≤ 2000 characters | |
data.result.quizzes[].questions[].responseText | string | The response in words: the chosen choices' text, true / false, the typed answer. |
data.result.quizzes[].questions[].respondent | one 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.castIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
data.result.variablesRequired | object[] | |
data.result.variables[].variableIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
data.result.variables[].aliasRequired | string | |
data.result.variables[].typeRequired | string≥ 1 characters | |
data.result.variables[].valueRequired | boolean | number | string | A story value: a boolean, a number, or a short text (a choice is its key). |
data.result.itemsRequired | object[] | |
data.result.items[].resultIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
data.result.items[].aliasRequired | string | |
data.result.items[].labelRequired | string | |
data.result.items[].kindRequired | string≥ 1 characters |
|
data.result.items[].valueRequired | number | boolean | |
data.result.totalsRequired | object | |
data.result.totals.scoreRequired | number≥ 0 | |
data.result.totals.maxScoreRequired | number≥ 0 | |
data.result.totals.percentRequired | number0–100 | |
data.result.totals.passed | boolean | |
data.result.totals.correctCountRequired | integer0–9007199254740991 | |
data.result.totals.questionCountRequired | integer0–9007199254740991 | |
data.result.totals.answeredCountRequired | integer0–9007199254740991 | |
data.result.totals.beatsCompletedRequired | integer0–9007199254740991 | |
data.result.totals.beatsTotalRequired | integer0–9007199254740991 | |
data.result.totals.completionRequired | number0–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
| Name | In | Type | Description |
|---|---|---|---|
Jami-SignatureRequired | header | string |
|
Jami-Event-IdRequired | header | string | The event's id: the same on every attempt and redelivery. Deduplicate on it. |
Jami-Event-TypeRequired | header | string | The event's |
Jami-Delivery-AttemptRequired | header | string | Which attempt this is: 1, then 2, 3… for the retries. |
Payload
| Field | Type | Description |
|---|---|---|
idRequired | string (uuid) | The event's id: the same on every attempt and redelivery ( |
typeRequired | "result.quiz_answered" | |
versionRequired | 1 | |
createdAtRequired | string (date-time) | An ISO 8601 instant. |
dataRequired | object | |
data.sessionRequired | object | The viewer session an event is about. |
data.session.idRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
data.session.projectIdRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
data.session.releaseIdRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
data.session.surfaceRequired | string≥ 1 characters | Where it was minted: a value of |
data.session.testRequired | boolean | Minted with a test key: keep it out of real records. |
data.session.apiKeyId | string (uuid) | The key it was minted with; absent for the project owner's own pages and keyless embeds. |
data.session.externalUserId | string1–200 characters | A secure embed's learner, as the integrator named them ( |
data.epochRequired | integer0–9007199254740991 | The session's epoch when it was answered (a rewind starts the next: see |
data.seqRequired | integer1–9007199254740991 | The answer's place in the session's story journal: a later answer has a higher number. |
data.answeredAtRequired | string (date-time) | An ISO 8601 instant. |
data.anchorRequired | object | Where in the story it was answered. |
data.anchor.visitRequired | integer1–9007199254740991 | |
data.anchor.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
data.anchor.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
data.quizIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
data.questionIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
data.respondentRequired | one 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.castIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
data.responseRequired | one 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.choiceIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
| When kind is “choices” | ||
data.response.choiceIdsRequired | string[]1–10 items | |
| When kind is “boolean” | ||
data.response.valueRequired | boolean | |
| When kind is “text” | ||
data.response.textRequired | string≤ 2000 characters | |
data.responseText | string | The response in words: the chosen choices' text, true / false, the typed answer. |
data.attemptRequired | integer1–9007199254740991 | |
data.finalRequired | boolean | No later attempt can change this question's outcome. |
data.correctRequired | boolean | |
data.pointsRequired | number≥ 0 | |
data.quizRequired | object | The quiz after this answer. |
data.quiz.quizIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
data.quiz.aliasRequired | string | |
data.quiz.title | string | |
data.quiz.statusRequired | string≥ 1 characters |
|
data.quiz.scoreRequired | number≥ 0 | |
data.quiz.maxScoreRequired | number≥ 0 | |
data.quiz.percentRequired | number0–100 | 0–100, one decimal. |
data.quiz.passed | boolean | Against the quiz's pass mark, once the quiz is completed. |
data.quiz.correctCountRequired | integer0–9007199254740991 | |
data.totalsRequired | object | The whole session after this answer. |
data.totals.scoreRequired | number≥ 0 | |
data.totals.maxScoreRequired | number≥ 0 | |
data.totals.percentRequired | number0–100 | |
data.totals.passed | boolean | |
data.totals.correctCountRequired | integer0–9007199254740991 | |
data.totals.questionCountRequired | integer0–9007199254740991 | |
data.totals.answeredCountRequired | integer0–9007199254740991 | |
data.totals.beatsCompletedRequired | integer0–9007199254740991 | |
data.totals.beatsTotalRequired | integer0–9007199254740991 | |
data.totals.completionRequired | number0–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
| Name | In | Type | Description |
|---|---|---|---|
Jami-SignatureRequired | header | string |
|
Jami-Event-IdRequired | header | string | The event's id: the same on every attempt and redelivery. Deduplicate on it. |
Jami-Event-TypeRequired | header | string | The event's |
Jami-Delivery-AttemptRequired | header | string | Which attempt this is: 1, then 2, 3… for the retries. |
Payload
| Field | Type | Description |
|---|---|---|
idRequired | string (uuid) | The event's id: the same on every attempt and redelivery ( |
typeRequired | "result.retracted" | |
versionRequired | 1 | |
createdAtRequired | string (date-time) | An ISO 8601 instant. |
dataRequired | object | |
data.sessionRequired | object | The viewer session an event is about. |
data.session.idRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
data.session.projectIdRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
data.session.releaseIdRequired | string (uuid) | A server-minted id (sessions, projects, releases, users): a UUID. |
data.session.surfaceRequired | string≥ 1 characters | Where it was minted: a value of |
data.session.testRequired | boolean | Minted with a test key: keep it out of real records. |
data.session.apiKeyId | string (uuid) | The key it was minted with; absent for the project owner's own pages and keyless embeds. |
data.session.externalUserId | string1–200 characters | A secure embed's learner, as the integrator named them ( |
data.epochRequired | integer0–9007199254740991 | The epoch the session goes on in: every answer listed was recorded in an earlier one. |
data.quizIdsRequired | string[]≥ 1 items | The quizzes some of whose answers the rewind erased. |
data.answersRequired | object[]≥ 1 items | Each answer erased. |
data.answers[].quizIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
data.answers[].questionIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
data.answers[].seqRequired | integer1–9007199254740991 | The erased answer's |
data.answers[].epochRequired | integer0–9007199254740991 | |
data.answers[].attemptRequired | integer1–9007199254740991 | |
data.toRequired | object | Where the story went back to: everything answered at or after it is gone. |
data.to.visitRequired | integer1–9007199254740991 | |
data.to.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
data.to.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
data.rewoundAtRequired | string (date-time) | An ISO 8601 instant. |
data.totalsRequired | object | The session after the erase. |
data.totals.scoreRequired | number≥ 0 | |
data.totals.maxScoreRequired | number≥ 0 | |
data.totals.percentRequired | number0–100 | |
data.totals.passed | boolean | |
data.totals.correctCountRequired | integer0–9007199254740991 | |
data.totals.questionCountRequired | integer0–9007199254740991 | |
data.totals.answeredCountRequired | integer0–9007199254740991 | |
data.totals.beatsCompletedRequired | integer0–9007199254740991 | |
data.totals.beatsTotalRequired | integer0–9007199254740991 | |
data.totals.completionRequired | number0–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
| Name | In | Type | Description |
|---|---|---|---|
Jami-SignatureRequired | header | string |
|
Jami-Event-IdRequired | header | string | The event's id: the same on every attempt and redelivery. Deduplicate on it. |
Jami-Event-TypeRequired | header | string | The event's |
Jami-Delivery-AttemptRequired | header | string | Which attempt this is: 1, then 2, 3… for the retries. |
Payload
| Field | Type | Description |
|---|---|---|
idRequired | string (uuid) | The event's id: the same on every attempt and redelivery ( |
typeRequired | "webhook.test" | |
versionRequired | 1 | |
createdAtRequired | string (date-time) | An ISO 8601 instant. |
dataRequired | object | |
data.endpointIdRequired | string (uuid) | The endpoint the test was sent to. |
data.messageRequired | string |