Introduction

Webhooks are a way to receive data from Vital. We frequently poll to receive data from the various providers. By registering webhooks, you avoid unnecessarily hitting our servers for data. We have several webhook event types that you can subscribe to. You can see these in the dashboard under the webhooks sections.

​

Historical Data Flow

When a user first connects a device to Vital, Vital backend pulls historical data. Historical data is all data that exists on a user’s account, prior to them linking their wearable account with Vital. This can take several minutes for all the data to be retrieved and to be readily accessible.

When data is available, the backend triggers a historical.data.<resource_type>.created webhook event. The resource_type is determined by the provider - more information on which resources a provider can support can be found here.

We send a webhook event for each resource a provider supports. In certain cases, where a user has large amounts of historical data, we send webhook events for each ordered-chunk (most-recent first). The is_final flag is used to indicate that the data collection is complete.

{
  "event_type": "historical.data.workouts.created",
  "data": {
    "user_id": "e9e072e8-...",
    "start_date": "2020-06-21T08:23:01+00:00",
    "end_date": "1996-11-02T14:39:28+00:00",
    "is_final": true,
    "provider": "zwift"
  }
}

When you receive the historical backfill event, you should make an API call for the specific resource you received the webhook event for. As an example, if you receive the event historical.data.workouts.created you should make a call to GET workout data from the API. Historical data can be quite big, so we don’t send the full payload in a webhook.

​

Daily Data Flow

After a user has connected and historical data is backfilled, any new data is sent in the payload of the daily.data.<resource_type>.created webhook. Each payload has an id associated with it, and we recommend storing this value. This is to support cases where data may be updated. If an instance of previously sent data is changed by the user, we issue a daily.data.<resource_type>.updated event. For example, the title of a workout can be edited, or the amount of calories a user has burnt can change throughout the day.

Examples of each payload are provided in the webhooks dashboard. You can send test events which contain the different payloads you may receive throughout the integrations lifecyle.

{
  "event_type": "daily.data.workouts.created",
  "data": {
    "id": "c90bd6fb-...",
    "average_hr": 198,
    "distance": 8544,
    "time_start": "2012-11-24T22:57:01+00:00",
    "time_end": "2017-04-22T04:57:31+00:00",
    "calories": 4470,
    "hr_zones": [8279],
    "user_id": "ab3247dc-...",
    "moving_time": 4719,
    "total_elevation_gain": 8967,
    "elev_high": 3868,
    "max_speed": 8371,
    "average_watts": 9029,
    "max_watts": 1551,
    "provider_id": "dolor ipsum reiciendis Lorem veniam elit. esse",
    "source": {
      "name": "Zwift",
      "slug": "zwift",
      "logo": "https://logo.png"
    }
  }
}

​

Connection Created

Once a connection between a provider and a user is established, we will send a webhook confirming it.

{
  "event_type": "provider.connection.created",
  "data": {
    "user_id": "4eca10f9-...",
    "source": {
      "source_name": "Strava",
      "source_slug": "strava",
      "source_logo": "https://storage.googleapis.com/vital-assets/strava.png"
    }
  }
}

​

Deep Dive into Vital Webhooks

​

Webhook Events

All our webhook events have the following structure. Each event consists of an event_type followed by a payload under the data key. The event_type specifies the type of data that is sent. You can see examples in the dashboard under Svix. You can also send example data via the Svix dashboard, under example events.

{
  "event_type": "daily.data.glucose.created",
  "data": "...event_specific_data"
}