# Webhook v2.1.0

Payload and fields of the version 2.1.0 webhook that Screeb sends on survey displays and answers.

This page describes version 2.1.0 of the webhook payload. How Screeb delivers it, retries it and signs it is the same for every version: see [Webhooks](https://developers.screeb.app/api-and-connectors/webhooks).

## 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 users will see the last scenario.
- User: Information about the visitor
- Response: A response is a chain of question+answers. A user sometimes has many responses to a single survey.
- Question
- Answer: An answer is part of a response. Each answer is associated with a question.
- Field: An answer may have many fields (for example, a multiple choice question)

## Migrate from v2.0.0

`response.hidden_fields` is split into 3 objects:

- `user.properties`: a snapshot of the user properties when the response starts.
- `response.context`: context data (URL, browser, locale, timezone, screen size...).
- `response.hidden_fields`: only the hidden fields set when the response starts.

Their properties can be nested:

```js
{
  // ...

  "context": {
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36",
    "browser": {
      "name": "chrome",
      "version": "1.2.3"
    }
  },

  // ...
}
```

## Example payload

Screeb sends each event as a JSON body in a `POST` request. A typical `response.ended` payload:

```js
{
  "event_id": "64c7ea3b-827b-4679-b25d-7fd61f6c3d33",
  "event_type": "response.ended",
  "version": "2.1.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
    },
    "user": {
      "anonymous_id": "2eb83fb4-b1b3-4e48-be48-a8fd9c4e5a7d",
      "user_id": "support@screeb.app",
      "name": "John Doe",
      "email": "support@screeb.app",
      "group_names": ["Screeb", "10-100-companies", "plan-enterprise"],
      "properties": {
        "firstname": "John",
        "lastname": "Doe",
        "email": "support@screeb.app",
        "plan": "free",
        "signup_at": "2020-03-01T02:03:04.56789Z",
        "last_seen_at": "2021-06-09T02:03:04.56789Z"
      }
    },
    "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": {
        "variable-from-crm": "blablabla"
      },
      "context": {
        "active_page": {
          "domain": "screeb.app",
          "path": "/solutions/product-analytics",
          "search": "utm_medium=email",
          "title": "In-app engaging surveys",
          "url": "https://screeb.app/solutions/product-analytics?utm_medium=email"
        },
        "library": {
          "name": "sdk-js",
          "source": "sdk-js",
          "source_type": "screeb",
          "version": "0.2.61"
        },
        "locale": "en-GB",
        "screen": {
          "height": 940,
          "scale": 1,
          "width": 2560
        },
        "timezone": "Europe/Paris",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36"
      },
      "question": {
        "id": "a44252c3-ef3d-4156-90d6-a3d6364516c0",
        "type": "input",
        "title": "How can we improve your experience?"
      },
      "answer": {
        "fields": [
          {
            "id": "c71dfe9d-6b47-452f-bda2-6091c13561b0",
            "type": "string",
            "value": "The new dashboard is buggy.",
            "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": {...} }
      ]
    }
  }
}
```

## Spec

### 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

| Field        | type         | Optional | description          |
| ------------ | ------------ | -------- | -------------------- |
| organization | Organization | No       | Organization details |
| channel      | Channel      | No       | Channel details      |
| survey       | Survey       | No       | Survey details       |
| user         | User         | No       | User details         |
| response     | Response     | No       | Response details     |

### Organization

| Field | type   | Optional | description                            |
| ----- | ------ | -------- | -------------------------------------- |
| id    | uuid   | No       | Unique identifier for the organization |
| name  | string | No       | Name of the Screeb account             |

### Channel

| Field | type   | Optional | description                                         |
| ----- | ------ | -------- | --------------------------------------------------- |
| id    | uuid   | No       | Unique identifier for the channel                   |
| type  | string | No       | Channel type (widget, android, ios, hosted-page...) |

### 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) |

### User

| Field        | type           | Optional | description                                        |
| ------------ | -------------- | -------- | -------------------------------------------------- |
| anonymous_id | uuid           | No       | Screeb identifier for the user                     |
| user_id      | string         | No       | Main user identifier                               |
| name         | string         | Yes      | User name (when available in identity properties)  |
| email        | string         | Yes      | User email (when available in identity properties) |
| group_names  | Array\<string> | Yes      | User groups                                        |
| properties   | object         | Yes      | Key/Value of user properties                       |

### 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"                                          |
| context                 | object         | Yes      | Key/Value of context data                                                                          |
| hidden_fields           | object         | Yes      | Key/Value of 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 event_type == `response.ended` ) |
| session_replay_url      | string         | Yes      | Full URL to the session replay associated with the response, when a session was recorded           |
| tags                    | Array\<string> | Yes      | Tags of the response                                                                               |

### Question

| Field          | type   | Optional | description                                                  |
| -------------- | ------ | -------- | ------------------------------------------------------------ |
| id             | uuid   | No       | Unique identifier for the question                           |
| correlation_id | uuid   | No       | Identifier of the question, shared by every scenario version |
| type           | string | No       | Type of question                                             |
| title          | string | No       | Label of the question                                        |

### Answer

| Field         | type           | Optional | description                                             |
| ------------- | -------------- | -------- | ------------------------------------------------------- |
| fields        | Field\[]       | No       | List of values. See the "Field" section                 |
| field         | Field          | No       | Deprecated: the first value only. Read `fields` instead |
| 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                                      |

### Field

| Field          | type    | Optional | description                                               |
| -------------- | ------- | -------- | --------------------------------------------------------- |
| id             | uuid    | No       | Unique identifier for the field                           |
| correlation_id | uuid    | No       | Identifier of the field, shared by every scenario version |
| type           | string  | No       | Value type: "string", "number", "time", "boolean"...      |
| value          | string  | No       | Printable value of the field (always string)              |
| text           | string  | Yes      | Value of the field, when type is "string"                 |
| number         | number  | Yes      | Value of the field, when type is "number"                 |
| bool           | boolean | Yes      | Value of the field, when type is "boolean"                |
| time           | string  | Yes      | Value of the field, when type is "time"                   |

NPS, CES and CSAT scores are sent as numbers, not as emojis. `text`, `number`, `bool` and `time` are left out when empty.

### Item

| Field    | type     | Optional | description                |
| -------- | -------- | -------- | -------------------------- |
| question | Question | No       | See the "Question" section |
| answer   | Answer   | No       | See the "Answer" section   |
