Webhooks & Events
Introduction
With Webhooks and ETL Pipelines, Vital pushes any new data or updates to your endpoint
or your ETL destination as soon as they are discovered.
Once the historical data backfill job of a specific resource has fully completed, Vital sends a Historical Pull Completion event for the resource:
Connection Created stage
When a user successfully connects a provider through Vital Link, Vital sends a Provider Connection Created event to acknowledge it:Event Type
Event Type
provider.connection.createdExample
Example
Check out the Provider Connection Created event in the Event Catalog.
Webhook Event
Historical Data Backfill stage
Vital also schedules jobs to backfill historical data upon connection establishment. Historical data are data that exist prior to the connection establishment. Because this can amount to months of data — and might potentially run into temporary provider-side API rate limits — these backfill jobs may take minutes to hours to complete.You can inspect the status of historical data backfill jobs of each individual user through Vital Dashboard or
Vital API.
Event Type
Event Type
historical.data.{RESOURCE}.createdUsage
Usage
This event is a data-less notification.Use the Vital Data Access API to fetch the resource you are interested in.Constrain your API call using the information in the Historical Pull Completion event. For example, the event includes the
provider slug as well as full datetime range which Vital has looked through.
Example
Example
Check out the Historical Workout Data Pull Completion event in the Event Catalog.
ETL Pipelines can opt-in to receive historical data as Vital Data Events
(as outlined below in the Incremental Data stage section).Note that Vital would still send the Historical Pull Completion event to signal the completion of the historical data backfill stage.
Incremental Data stage
Once the historical data backfill stage completes, Vital monitors for new data and changes. Whenever new data or changes are discovered, Vital sends them out as Data Events as soon as possible:You can inspect the state of incremental data updates of each individual user through Vital Dashboard or
Vital API.
Event Types
Event Types
- Initial discovery —
daily.data.{RESOURCE}.created - Subsequent updates —
daily.data.{RESOURCE}.updated
Treat the
daily.data prefix as a misnomer for Incremental Data. It does not imply a daily delivery schedule.Usage
Usage
Vital sends out Data Events as soon as we discover new or updated entries as reported by a provider. This also implies:
-
Vital does not prioritize or aggregate Data Events across providers:
- You may receive multiple events of the same type from a single provider, because the provider supports multiple sources, devices or apps (e.g., iPhone sleeps and Apple Watch sleeps from Apple HealthKit);
- You may receive multiple events of the same type from multiple providers, because the user has connected to multiple providers.
-
There is no standard Data Event delivery frequency or schedule across providers and resources:
- Some may be sent only once per day;
- Some may be sent multiple times at irregular times;
- Some may appear to be sent on a regular schedule throughout the day.
Vital also offers the Horizon AI Aggregation API for your data aggregation
and consolidation needs.
Example
Example
Check out the Workout Created event in the Event Catalog.
The event structure and deduplication semantic of summary types and timeseries types have a few key differences. Please refer to Event Structure for a more in-depth discussion.
Deep Dive into Vital Webhooks
Managing Webhooks
You can manage your team’s webhooks programmatically using our Webhooks API. This API allows you to:- CRUD (create/read/update/delete) your webhooks
- Manage webhook headers
- Update webhook secrets
Authenticating Webhooks
You can verify the webhook signature. Each webhook request we send includes these three headers:svix-idsvix-timestampsvix-signature