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

# Introduction

> Introduction to Junction webhooks that push new data and connection lifecycle updates to your configured HTTP endpoints in real time.

With Webhooks and [ETL Pipelines](/webhooks/etl-pipelines/overview), Junction pushes any new data or updates to your endpoint
or your ETL destination as soon as they are discovered.

## Connection Created stage

When a user successfully connects a provider through [Junction Link](/wearables/connecting-providers/introduction), Junction sends a
Provider Connection Created event to acknowledge it:

<AccordionGroup>
  <Accordion title="Event Type" defaultOpen>
    `provider.connection.created`
  </Accordion>

  <Accordion title="Example" defaultOpen>
    Check out the [Provider Connection Created event](/event-catalog/provider.connection.created) in the Event Catalog.

    ```json Webhook Event theme={null}
    {
      "event_type": "provider.connection.created",
      "data": {
        "user_id": "4eca10f9-...",
        "provider": {
          "name": "Strava",
          "slug": "strava",
          "logo": "https://storage.googleapis.com/vital-assets/strava.png"
        },
        "resource_availability": { ... }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Historical Data Backfill stage

Junction 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](/wearables/providers/introduction#historical-data-pull-range)
— and might potentially run into temporary provider-side API rate limits — these backfill jobs may take minutes to hours to complete.

<Note>
  You can inspect the status of historical data backfill jobs of each individual user through [Junction Dashboard](https://app.junction.com) or
  [Junction API](/api-reference/data/introspection/historical-pulls).
</Note>

Once the historical data backfill job of a specific [resource](/wearables/providers/resources) has **fully** completed, Junction sends a **Historical Pull Completion** event for the resource:

<AccordionGroup>
  <Accordion title="Event Type" defaultOpen>
    `historical.data.{RESOURCE}.created`
  </Accordion>

  <Accordion title="Usage" defaultOpen>
    This event is a data-less notification.

    Use the [Junction Data Access API](/api-reference/data/sleep/get-summary) 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](/wearables/providers/introduction) slug as well as the full datetime range that Junction has looked through.
  </Accordion>

  <Accordion title="Example" defaultOpen>
    Check out the [Historical Workout Data Pull Completion event](/event-catalog/historical.data.workouts.created) in the Event Catalog.

    ```json theme={null}
    {
      "event_type": "historical.data.workouts.created",
      "data": {
        "user_id": "e9e072e8-...",
        "start_date": "2020-06-21T08:23:01+00:00",
        "end_date": "2024-11-02T14:39:28+00:00",
        "provider": "zwift"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

<Note>
  [ETL Pipelines](/webhooks/etl-pipelines/overview) can opt-in to receive historical data as *Junction Data Events*
  (as outlined below in the [Incremental Data stage](#incremental-data-stage) section).

  Note that Junction would still send the Historical Pull Completion event to signal the completion of the historical data backfill stage.
</Note>

## Incremental Data stage

Once the historical data backfill stage completes, Junction [monitors for new data and changes](/wearables/providers/update-frequency).

Whenever new data or changes are discovered, Junction sends them out as **Data Events** as soon as possible:

<Note>
  You can inspect the state of incremental data updates of each individual user through [Junction Dashboard](https://app.junction.com) or
  [Junction API](/api-reference/data/introspection/user-resources).
</Note>

<AccordionGroup>
  <Accordion title="Event Types" defaultOpen>
    * Initial discovery — `daily.data.{RESOURCE}.created`
    * Subsequent updates — `daily.data.{RESOURCE}.updated`

    <Warning>
      Treat the `daily.data` prefix as a misnomer for *Incremental Data*. It **does not** imply a daily delivery schedule.
    </Warning>
  </Accordion>

  <Accordion title="Usage" defaultOpen>
    Junction sends out *Data Events* as soon as we discover new or updated entries as reported by a provider. This also implies:

    1. Junction 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.

    2. 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.

    Your system typically would ingest relevant Junction Data Events into a database.

    You can query the database with any business rules and query constraints suitable to your product experience. This may include
    your own data prioritization rules based on, e.g., [Source Type](/wearables/providers/data-attributions#source-type).

    <Note>
      Junction also offers the [Junction Sense Aggregation API](/sense/overview) for your data aggregation
      and consolidation needs.
    </Note>
  </Accordion>

  <Accordion title="Example" defaultOpen>
    Check out the [Workout Created event](/event-catalog/daily.data.workouts.created) in the Event Catalog.

    <Warning>The event structure and deduplication semantics of [summary types](/wearables/providers/resources) and [timeseries types](/wearables/providers/resources) have a few key differences. Please refer to [Event Structure](/webhooks/event-structure) for a more in-depth discussion.</Warning>

    ```json theme={null}
    {
      "event_type": "daily.data.workouts.created",
      "data": {
        "id": "c90bd6fb-...",
        "average_hr": 198,
        "distance": 8544,
        "time_start": "2024-11-24T22:57:01+00:00",
        "time_end": "2024-11-25T04:57:31+00:00",
        "calories": 4470,
        "hr_zones": [8279],
        "user_id": "ab3247dc-...",
        ...,
        "provider_id": "51278201336",
        "source": {
          "provider": "zwift",
          "type": "unknown"
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Deep Dive into Junction Webhooks

<div
  style={{
position: "relative",
paddingBottom: "56.872037914691944%",
height: 0
}}
>
  <iframe
    src="https://www.loom.com/embed/0121d272e21b44049dd4d418302580a5?sid=0dc174e1-20e6-4fd9-9824-0fc2d5eaf95f"
    frameBorder={0}
    webkitallowfullscreen=""
    mozallowfullscreen=""
    allowFullScreen=""
    style={{
  position: "absolute",
  top: 0,
  left: 0,
  width: "100%",
  height: "100%"
}}
    loading="lazy"
  />
</div>

### Managing Webhooks

You can manage your team's webhooks programmatically using our [Webhooks API](/api-reference/org-management/team-webhook/list). 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-id`
* `svix-timestamp`
* `svix-signature`

You'll also need your webhook secret, which you can find in your Junction Dashboard > Webhooks > Endpoint tabs under "Signing Secret".

**Option 1:** Use a Svix SDK

If you're using a compatible language, the easiest way is to utilize the [official Svix SDKs](https://docs.svix.com/receiving/verifying-payloads/how), which handle signature verification for you.

**Option 2:** Manual Verification

If the Svix SDKs are not an option, you can manually verify them following the instructions [here](https://docs.svix.com/receiving/verifying-payloads/how-manual).