Skip to content
HealthSync Docs

Event Envelope

Every event emitted by HealthSync uses this envelope. The envelope handles classification, provenance, and delivery routing. Data items inside data[] are self-contained with their own identity, timestamps, and versioning.

Structure

Section titled “Structure”
{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "schema_version": "1.1",
  "event_type": "activity",
  "stream": "session",


  "provider": "fitbit",
  "sources": [
    {
      "provider_notification_id": "notif-abc123",
      "fetched_at": 1742585000000
    }
  ],
  "devices": [
    {
      "device_id": "dev-001",
      "name": "Charge 6",
      "model": "FB423",
      "provider_device_id": "dev-001"
    }
  ],


  "tenant_id": "tenant-uuid",
  "user_id": "user-uuid",
  "external_user_ref": "your-user-123",
  "connection_id": "conn-uuid",


  "emitted_at": 1742585400000,


  "data": [
    // array of type-specific data items
  ]
}

Field Reference

Section titled “Field Reference”

| Field | Type | Description | |-------|------|-------------| | event_id | string (uuid) | Unique per emission. Re-processing the same data produces a new event_id. | | schema_version | string | Envelope schema version for forward compatibility. | | event_type | string | Discriminator for the data shape. All items in data[] share this type. | | stream | string | Stream tier: "session", "snapshot", "timeseries", "aggregate", or "profile". | | provider | string | Source provider identifier (e.g., "fitbit", "garmin", "oura"). | | sources | array | Notification references that triggered this event. Empty [] for backfill or non-notification events. | | sources[].provider_notification_id | string \| null | The provider notification that triggered the fetch. | | sources[].fetched_at | number (epoch ms) | When HealthSync fetched in response to the notification. | | devices | array | Device registry for this event. Data items reference devices by device_id. | | devices[].device_id | string | HealthSync-scoped device identifier. | | devices[].name | string \| null | Device display name. | | devices[].model | string \| null | Device model identifier. | | devices[].provider_device_id | string \| null | Provider’s native device ID. | | tenant_id | string | Target tenant. | | user_id | string | Target user within the tenant (HealthSync internal tenant_user_id). | | external_user_ref | string | Tenant-provided external user reference echoed from connect-time user creation. | | connection_id | string | The connection that produced this data. | | emitted_at | number (epoch ms) | When HealthSync emitted this event. | | data | array | One or more data items, all of the same event_type. |

Sources

Section titled “Sources”

The sources array records which provider notifications triggered this event:

  • Notification-triggered events: One or more source entries with fetched_at timestamps.
  • Backfill / replay events: Empty array [].
  • Manual / scheduled fetches: Empty array [].

Devices

Section titled “Devices”

The devices array is a registry of devices relevant to this event. Individual data items reference devices by device_id. When device attribution is unavailable, a data item sets device_id to null.