Event Envelope

Every event emitted by Nexus 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.

Caution

One envelope always carries exactly one event_type. All items in data[] share that type. This is a permanent architectural invariant — event_type determines webhook routing.

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

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 Nexus fetched in response to the notification.
devices	array	Device registry for this event. Data items reference devices by device_id.
devices[].device_id	string	Nexus-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 (Nexus 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 Nexus emitted this event.
data	array	One or more data items, all of the same event_type.

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

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.