> ## Documentation Index
> Fetch the complete documentation index at: https://docs.junction.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Event Structure

> Reference for the standard webhook event payload structure including event_type, data, team_id, user_id, and client_user_id fields.

All our webhook events have the following standard structure:

* A top-level `event_type` field, specifying the payload type contained in the `data` field.
* A top-level `data` field containing the event-specific payload.
* A set of top-level fields describing the event subject:
  * `team_id`: Your Junction Team ID.
  * `user_id`: The unique Junction User ID.
  * `client_user_id`: Your application user reference you declared for [the Junction User](/api-reference/user/create-user).

Schemas and examples are available through [the Event Catalog tab in the Webhooks section of our Web app](https://app.junction.com).

<CodeGroup>
  ```json Basic event structure theme={null}
  {
    "data": {
      # ... event specific data
    },
    "event_type": "daily.data.glucose.created",
    "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2",
    "client_user_id": "01HW3FSNVCHC3B2QB5N0ZAAAVG",
    "team_id": "6b74423d-0504-4470-9afb-477252ccf67a"
  }
  ```

  ```json Example: Provider connection created theme={null}
  {
    "data": {
      "source": {
        "logo": "https://storage.googleapis.com/vital-assets/freestyle.png",
        "name": "Freestyle Libre BLE",
        "slug": "freestyle_libre_ble"
      },
      "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2"
    },
    "event_type": "provider.connection.created",
    "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2",
    "client_user_id": "01HW3FSNVCHC3B2QB5N0ZAAAVG",
    "team_id": "6b74423d-0504-4470-9afb-477252ccf67a"
  }
  ```
</CodeGroup>

## Wearable data events

Wearable data events have the following extended standard structure:

* An `event_type` field for differentiating the payload contained in the data field.
* A `data` field, which comprises:
  * The UUID of the Junction user for which this event is intended — note that this is not the `client_user_id` of the Junction user. (JSON path: `$.data.user_id`)
  * The metadata about the data source of this event (JSON path: `$.data.source`)
    * `name`: The human-readable name of the source
    * `slug`: The stable identifier Junction assigned to the source — see [Supported providers](/wearables/providers/introduction) for the complete list.
    * `logo`: The URL to an icon representing the source.
  * Any number of event-specific fields.

```json Wearable data event structure theme={null}
{
  "data": {
    # ... event specific fields

    # Common wearable data event fields
    "source": {
      "logo": "https://path/to/example",
      "name": "Fitbit",
      "slug": "fitbit"
    },
    "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2"
  },
  "event_type": "daily.data.glucose.created",
  "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2",
  "client_user_id": "01HW3FSNVCHC3B2QB5N0ZAAAVG",
  "team_id": "6b74423d-0504-4470-9afb-477252ccf67a"
}
```

### Summary types

Each time a [summary object](/wearables/providers/resources) is created or updated, Junction emits a data event for the occurrence.
The object is made available directly at the top-level `data` field (JSON path: `$.data`), alongside the standard fields listed above.

<Note>
  Each summary is uniquely identified by its ID (`$.id`).

  Given the same ID, the latest version of a summary you received **replaces** all its previous versions.
</Note>

<CodeGroup>
  ```json Summary data event structure theme={null}
  {
    "data": {
      # ... All summary object fields

      # Common wearable data event fields
      "source": {
        "logo": "https://path/to/example",
        "name": "Fitbit",
        "slug": "fitbit"
      },
      "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2"
    },
    "event_type": "daily.data.activity.created",
    "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2",
    "client_user_id": "01HW3FSNVCHC3B2QB5N0ZAAAVG",
    "team_id": "6b74423d-0504-4470-9afb-477252ccf67a"
  }
  ```

  ```json Example: Activity updated theme={null}
  {
    "data": {
      "calendar_date": "2023-05-17",
      "calories_active": 134,
      "calories_total": 1006,
      "daily_movement": 1162,
      "date": "2023-05-17T00:00:00+00:00",
      "distance": 1162,
      "floors_climbed": 2,
      "high": null,
      "id": "715dd6a5-0c67-471c-b5fe-9681a980a2c2",
      "low": null,
      "medium": null,
      "steps": 1496,
      "timezone_offset": 3600,

      # Common wearable data event fields
      "source": {
        "logo": "https://storage.googleapis.com/vital-assets/apple_health.png",
        "name": "Apple HealthKit",
        "slug": "apple_health_kit"
      },
      "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2"
    },
    "event_type": "daily.data.activity.updated",
    "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2",
    "client_user_id": "01HW3FSNVCHC3B2QB5N0ZAAAVG",
    "team_id": "6b74423d-0504-4470-9afb-477252ccf67a"
  }
  ```
</CodeGroup>

### Timeseries types (except for Workout Streams)

Each time a batch of [timeseries samples](/wearables/providers/resources) has been created or updated, Junction emits a data event for the batch of samples.
The samples are made available under an inner `data` field under the top-level `data` field (JSON path: `$.data.data`).

<Note>
  Each timeseries sample is uniquely identified by a compound key of:

  * the timeseries resource type;
  * the source provider;
  * the [Source Type](/wearables/providers/data-attributions#source-type); and
  * the sample timestamp.

  Given the same compound key, the latest value of a sample you received **replaces** all the previous values.
</Note>

<Info>While most timeseries data are immutable, there have been exceptions of some sources aggregating some data types using time bucketing,
and some may even send updates ASAP on time buckets that have incomplete data. For example, activity timeseries data from Apple HealthKit
(integration in production) and Garmin (integration planned) do exhibit such behavior.<br /><br />These exceptions are the rationale behind the recommended deduplication semantic as stated above.</Info>

<CodeGroup>
  ```json Timeseries data event structure theme={null}
  {
    "data": {
      "data": [
        {
          "timestamp": "2023-05-16T10:00:00+00:00",
          "timezone_offset": 3600,
          "type": null,
          "unit": "count",
          "value": 237
        },
        {
          "timestamp": "2023-05-16T11:00:00+00:00",
          "timezone_offset": 3600,
          "type": null,
          "unit": "count",
          "value": 451
        },
        # ... other timeseries samples in the batch
      ],
      "source_id": 16,

      # Common wearable data event fields
      "source": {
        "logo": "https://storage.googleapis.com/vital-assets/apple_health.png",
        "name": "Apple HealthKit",
        "slug": "apple_health_kit"
      },
      "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2"
    },
    "event_type": "daily.data.steps.created",
    "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2",
    "client_user_id": "01HW3FSNVCHC3B2QB5N0ZAAAVG",
    "team_id": "6b74423d-0504-4470-9afb-477252ccf67a"
  }
  ```

  ```json Example: Calories Active created theme={null}
  {
    "data": {
      "data": [
        {
          "timestamp": "2023-05-17T07:00:00+00:00",
          "start": "2023-05-17T07:00:00+00:00",
          "end": "2023-05-17T08:00:00+00:00",
          "timezone_offset": 3600,
          "type": "",
          "unit": "kcal",
          "value": 39.518054167148996
        },
        {
          "timestamp": "2023-05-17T08:00:00+00:00",
          "start": "2023-05-17T08:00:00+00:00",
          "end": "2023-05-17T09:00:00+00:00",
          "timezone_offset": 3600,
          "type": "",
          "unit": "kcal",
          "value": 31.270257990822234
        },
        {
          "timestamp": "2023-05-17T09:00:00+00:00",
          "start": "2023-05-17T09:00:00+00:00",
          "end": "2023-05-17T09:01:00+00:00",
          "timezone_offset": 3600,
          "type": "",
          "unit": "kcal",
          "value": 5.733999999999999
        }
      ],
      "source_id": 16,

      # Common wearable data event fields
      "source": {
        "logo": "https://storage.googleapis.com/vital-assets/apple_health.png",
        "name": "Apple HealthKit",
        "slug": "apple_health_kit"
      },
      "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2"
    },
    "event_type": "daily.data.calories_active.created",
    "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2",
    "client_user_id": "01HW3FSNVCHC3B2QB5N0ZAAAVG",
    "team_id": "6b74423d-0504-4470-9afb-477252ccf67a"
  }
  ```
</CodeGroup>

### Workout Streams

While Workout Streams are classified as a timeseries type, they contain a huge amount of timeseries data,
which cannot be delivered by our webhook message transport.

So events for Workout Streams are shallow, with only some minimal metadata about the workout. Successful
reception of the event indicates that the data are available to be read via our REST API,
e.g., [the Workout Stream endpoint](/api-reference/data/workouts/get-stream) `GET /v2/timeseries/workouts/{workout_id}/stream`.

```json Workout Stream created theme={null}
{
  "data": {
    "message": "Due to payload size limits, to access the workout stream, please use the /workouts/edc80dd0-8cc8-4ec8-8b80-931fd9a3309a/stream endpoint.",
    "provider_id": "51278201336",
    "sport": {
      "id": 57,
      "name": "Other",
      "slug": "other"
    },
    "workout_id": "fdc70dd0-8cc8-4ec8-8b80-121fd9a3302a",

    # Common wearable data event fields
    "source": {
      "logo": "https://storage.googleapis.com/vital-assets/fitbit.png",
      "name": "Fitbit",
      "slug": "fitbit"
    },
    "user_id": "bf6222fb-3b81-4201-9630-118bfee01e03"
  },
  "event_type": "daily.data.workout_stream.created",
  "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2",
  "client_user_id": "01HW3FSNVCHC3B2QB5N0ZAAAVG",
  "team_id": "6b74423d-0504-4470-9afb-477252ccf67a"
}
```