Webhook v1.3.0
Payload and fields of the version 1.3.0 webhook that Screeb sends on survey displays and answers.
This page describes version 1.3.0 of the webhook payload. How Screeb delivers it, retries it and signs it is the same for every version: see Webhooks.
Entities
Section titled “Entities”- Organization: A Screeb account, shared by many Screeb users of your company
- Channel: A distribution channel for your survey (JavaScript tag, Android SDK, iOS SDK…)
- Survey
- Survey scenario: A versioned survey: on survey update, your flow is saved in a new scenario. New respondents will see the last scenario.
- Respondent: Information about the visitor
- Response: A response is a chain of question+answers. A respondent sometimes has many responses to a single survey.
- Question
- Answer: An answer is part of a response. Each answer is associated with a question.
Example payload
Section titled “Example payload”Screeb sends each event as a JSON body in a POST request. A typical response.ended payload:
{ "event_id": "64c7ea3b-827b-4679-b25d-7fd61f6c3d33", "event_type": "response.ended", "version": "1.3.0", "time": "2021-07-29T13:45:09.325344042Z", "time_ms": 1627566309325, "payload": { "organization": { "id": "b5969d13-5e5e-4648-9806-5339ddafd984", "name": "ACME" }, "channel": { "id": "411ee7c3-7e64-409f-9d75-c782b3f73aa4", "type": "android" }, "survey": { "id": "9b913c69-3daf-4a6e-a26d-042004fc7881", "name": "Measure NPS", "scenario_id": "cc4a3710-e8ee-4672-a35c-5c17485ec441", "scenario_version": 9, "scenario_time": "2021-07-29T00:08:31.069497Z", "scenario_time_ms": 1627517311069 }, "respondent": { "id": "2eb83fb4-b1b3-4e48-be48-a8fd9c4e5a7d", "alias": "support@screeb.app", "aliases": [ "2eb83fb4-b1b3-4e48-be48-a8fd9c4e5a7d", "support@screeb.app" ], "name": "John Doe", "email": "support@screeb.app", "group_names": ["Screeb", "10-100-companies", "plan-enterprise"] }, "response": { "id": "5854a797-628c-4906-bb4c-da03e418cf47", "locale": "en-US", "time": "2021-07-29T13:44:59.831Z", "time_ms": 1627918228831, "time_to_complete_second": 34, "completion": "fully_completed", "hidden_fields": { "firstname": "John", "lastname": "Doe", "email": "support@screeb.app", "locale": "en-US", "support": "desktop", "timezone": -120, "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...." }, "question": { "id": "25c06995-b8aa-45d1-a03d-cd885a6ead58", "correlation_id": "a44252c3-ef3d-4156-90d6-a3d6364516c0", "type": "input", "title": "How can we improve your experience?" }, "answer": { "field": { "id": "ca679de0-6f45-485d-be00-77aa15677d23", "correlation_id": "c71dfe9d-6b47-452f-bda2-6091c13561b0", "type": "string", "value": "The new dashboard is buggy.", // deprecated "text": "The new dashboard is buggy." }, "replied_at": "2021-07-29T13:45:09.286Z", "replied_at_ms": 1627566309286, "tags": ["screeb", "feedback"] }, "tags": ["screeb", "feedback"], "items": [ { "question": {...}, "answer": {...} }, { "question": {...}, "answer": {...} }, { "question": {...}, "answer": {...} } ] } }}Metadata
Section titled “Metadata”| Field | Type | Optional | description |
|---|---|---|---|
| event_id | uuid | No | Unique id of the event, unchanged on retries |
| retry_count | int | No | Always 0 |
| event_type | enum: response.displayed, response.answered or response.ended |
No | Type of event sent over webhook |
| time | Date | No | Date of event |
| time_ms | long | No | Timestamp of event in millisecond |
| version | string | No | Semver version of the webhook payload |
| payload | <Payload> | No | See “Payload” section |
Payload
Section titled “Payload”| Field | type | Optional | description |
|---|---|---|---|
| organization | Organization | No | Organization details |
| channel | Channel | No | Channel details |
| survey | Survey | No | Survey details |
| respondent | Respondent | No | Respondent details |
| response | Response | No | Response details |
Organization
Section titled “Organization”| Field | type | Optional | description |
|---|---|---|---|
| id | uuid | No | Unique identifier for the organization |
| name | string | No | Name of the Screeb account |
Channel
Section titled “Channel”| Field | type | Optional | description |
|---|---|---|---|
| id | uuid | No | Unique identifier for the channel |
| type | string | No | Channel type (widget, android, ios, hosted-page…) |
Survey
Section titled “Survey”| Field | type | Optional | description |
|---|---|---|---|
| id | uuid | No | Unique identifier for the survey |
| name | string | No | Name of the survey |
| scenario_id | string | No | Unique identifier for the survey scenario |
| scenario_version | int | No | Version number of the survey scenario |
| scenario_time | Date | No | Date of the scenario edition |
| scenario_time_ms | int | No | Timestamp of the scenario edition (millisecond) |
Respondent
Section titled “Respondent”| Field | type | Optional | description |
|---|---|---|---|
| id | uuid | No | Screeb identifier for the respondent |
| alias | string | No | Main respondent identifier |
| aliases | Array<string> | No | List of respondent aliases |
| name | string | Yes | Respondent name (when available in identity properties) |
| string | Yes | Respondent email (when available in identity properties) | |
| group_names | Array<string> | Yes | Respondent groups |
Response
Section titled “Response”| Field | type | Optional | description |
|---|---|---|---|
| id | uuid | No | Unique identifier for the response |
| locale | string | Yes | Locale of the respondent |
| time | Date | No | Date of response start |
| time_ms | long | No | Timestamp of response start in millisecond |
| time_to_complete_second | long | Yes | Seconds between survey display and response end (when event_type == response.ended) |
| completion | string | Yes | “not_started”, “partially_completed” or “fully_completed” |
| hidden_fields | object | Yes | Key/Value of the hidden fields |
| question | Question | Yes | See the “Question” section (when event_type == response.answered) |
| answer | Answer | Yes | See the “Answer” section (when event_type == response.answered) |
| items | Item[] | No | See the “Item” section (when event_type == response.answered or response.ended) |
| session_replay_url | string | Yes | Full URL to the session replay associated with the response, when a session was recorded |
Question
Section titled “Question”| Field | type | Optional | description |
|---|---|---|---|
| id | uuid | No | Unique identifier for the question |
| correlation_id | uuid | No | Correlation identifier for the question (shared over many survey scenario versions) |
| type | string | No | Type of question |
| title | string | No | Label of the question |
Answer
Section titled “Answer”| Field | type | Optional | description |
|---|---|---|---|
| field.id | uuid | No | Unique identifier for the field (a button, a score, an input…) |
| field.correlation_id | uuid | No | Correlation identifier for the field (shared over many survey scenario versions) |
| field.type | string | No | Value type: “string”, “number”, “time”, “boolean”… |
| field.value | string | No | Deprecated: value of the answer, always a string |
| field.text | string | Yes | Value of the answer, when type is “string” |
| field.number | number | Yes | Value of the answer, when type is “number” |
| field.bool | boolean | Yes | Value of the answer, when type is “boolean” |
| field.time | string | Yes | Value of the answer, when type is “time” |
| replied_at | Date | No | Date of the answer |
| replied_at_ms | int | No | Timestamp of the answer (millisecond) |
| tags | Array<string> | Yes | Tags of the answer |
NPS, CES and CSAT scores are sent as numbers, not as emojis. text, number, bool and time are left out when empty.
| Field | type | Optional | description |
|---|---|---|---|
| question | Question | No | See the “Question” section |
| answer | Answer | No | See the “Answer” section |