Event Reference | Sahha Docs

Introduction

This reference documents the exact JSON structure for each webhook event type. Use these schemas to parse incoming webhook payloads and map them to your data models.

Webhook payloads differ from API responses

The JSON structure delivered via webhooks includes additional metadata fields (like accountId, externalId, and version) that may not appear in standard API responses. Always use these schemas when handling webhook events.

Score

Event

ScoreCreatedIntegrationEvent

Fired when a health score is generated or updated. Includes the score value, state, and all contributing factors.

id string

Unique identifier for this score record

profileId string

UUID of the profile this score belongs to

accountId string

UUID of the account that owns the profile

externalId string

Your external identifier for the user

type string

Score type: activity, sleep, readiness, wellbeing, mental_wellbeing

state string nullable

Severity level: minimal, low, medium, high

score float nullable

Normalized score from 0.0 to 1.0 where 1.0 is optimal

factors ScoreFactor[]

Array of contributing factors with individual scores

dataSources string[]

Data sources used to calculate this score (e.g., age, sleep, activity)

scoreDateTime datetime

The date this score represents (ISO 8601 format)

createdAtUtc datetime

UTC timestamp when the score was created

version float

Version of the scoring algorithm used

Example Payload

json

{
	"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
	"profileId": "c9bf9e57-1685-4c89-bafb-ff5af830be8a",
	"accountId": "a3c1e8d2-4f6b-4a9c-8e7d-2b5f1c3a9e6b",
	"externalId": "user_12345",
	"type": "sleep",
	"state": "high",
	"score": 0.85,
	"factors": [
		{
			"id": "sleep_duration",
			"name": "sleep_duration",
			"value": 7.5,
			"goal": 8.0,
			"score": 0.94,
			"state": "high",
			"unit": "hour"
		},
		{
			"id": "sleep_regularity",
			"name": "sleep_regularity",
			"value": 0.82,
			"goal": 0.9,
			"score": 0.91,
			"state": "high",
			"unit": "index"
		}
	],
	"dataSources": ["age", "sleep"],
	"scoreDateTime": "2025-01-22T00:00:00+00:00",
	"createdAtUtc": "2025-01-22T06:30:00Z",
	"version": 1.1
}

Object

ScoreFactor

Each factor in the factors array follows this structure:

id string

Unique identifier for the factor

name string

Factor name (e.g., sleep_duration, activity_steps)

value float nullable

The actual measured value

goal float nullable

Target value for optimal health

score float nullable

Factor score from 0.0 to 1.0

state string nullable

Factor state: minimal, low, medium, high

unit string

Unit of measurement

Biomarker

Event

BiomarkerCreatedIntegrationEvent

Fired when a biomarker value is calculated. Biomarkers are standardized health metrics like steps, heart rate, or sleep duration.

id string

Unique identifier for this biomarker record

profileId string

UUID of the profile this biomarker belongs to

accountId string

UUID of the account that owns the profile

externalId string

Your external identifier for the user

category string

Biomarker category: activity, sleep, body, vitals, engagement

type string

Biomarker type (e.g., steps, heart_rate_resting, sleep_duration)

periodicity string

Data frequency: daily, weekly, monthly, or none

aggregation string

Aggregation method: total, average, maximum, minimum, or none

value string

The calculated biomarker value (as string for precision)

unit string

Unit of measurement (e.g., count, hour, bpm, kcal)

valueType string

Data type of the value: integer, float, boolean, string

startDateTime string

Start of the measurement period (ISO 8601)

endDateTime string

End of the measurement period (ISO 8601)

createdAtUtc datetime

UTC timestamp when the biomarker was created

version float

Version of the biomarker calculation

Example Payload

json

{
	"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
	"profileId": "c9bf9e57-1685-4c89-bafb-ff5af830be8a",
	"accountId": "a3c1e8d2-4f6b-4a9c-8e7d-2b5f1c3a9e6b",
	"externalId": "user_12345",
	"category": "activity",
	"type": "steps",
	"periodicity": "daily",
	"aggregation": "total",
	"value": "8547",
	"unit": "count",
	"valueType": "integer",
	"startDateTime": "2025-01-22T00:00:00+00:00",
	"endDateTime": "2025-01-22T23:59:59+00:00",
	"createdAtUtc": "2025-01-22T18:30:00Z",
	"version": 1.0
}

Archetype

Event

ArchetypeCreatedIntegrationEvent

Fired when a user is assigned an archetype. Archetypes categorize users into behavioral patterns like activity level or sleep chronotype.

id string

Unique identifier for this archetype record

profileId string

UUID of the profile this archetype belongs to

accountId string

UUID of the account that owns the profile

externalId string

Your external identifier for the user

name string

Archetype category name (e.g., activity_level, chronotype, sleep_pattern)

value string

Assigned archetype value (e.g., early_bird, night_owl, highly_active)

dataType string

Data type of the value

periodicity string

How often the archetype is recalculated: daily, weekly, monthly

ordinality integer

Rank order when multiple archetypes exist (0-based)

startDateTime datetime

Start of the analysis period

endDateTime datetime

End of the analysis period

createdAtUtc datetime

UTC timestamp when the archetype was assigned

version float

Version of the archetype algorithm

Example Payload

json

{
	"id": "d4e5f6a7-b8c9-0123-def4-567890123456",
	"profileId": "c9bf9e57-1685-4c89-bafb-ff5af830be8a",
	"accountId": "a3c1e8d2-4f6b-4a9c-8e7d-2b5f1c3a9e6b",
	"externalId": "user_12345",
	"name": "chronotype",
	"value": "early_bird",
	"dataType": "string",
	"periodicity": "weekly",
	"ordinality": 0,
	"startDateTime": "2025-01-15T00:00:00Z",
	"endDateTime": "2025-01-22T00:00:00Z",
	"createdAtUtc": "2025-01-22T06:00:00Z",
	"version": 1.0
}

Tag

Event

TagReceivedIntegrationEvent

Fired when a tag is received—a time-bound categorical label such as a symptom, medication, shift, or subscription. Tags arrive from the SDK, Sahha's platform integrations, or your own backend, and stream in the same shape they were sent.

id string

Server-generated identifier. Identity is derived from name, type, source, and startDateTime under the profile

profileId string

UUID of the profile this tag belongs to

accountId string

UUID of the account that owns the profile

externalId string

Your external identifier for the user

type string

event (point in time) or state (window of time)

category string nullable

Optional bucket—reserved (symptom, reproductive) or any custom value

name string

The primary signal—reserved name or custom

value string nullable

Optional severity, dose, or variant. May be null for presence-only flags

source string

Which system produced the tag. SDK and integrations set this automatically; backend uploads typically use a reverse-DNS string (e.g. acme.workforce)

startDateTime datetime

When the tag began (ISO 8601)

endDateTime datetime nullable

When the tag ended. Null for events; may be null for open states

receivedAtUtc datetime

UTC timestamp when Sahha received the tag

additionalProperties object<string,string> nullable

Auxiliary metadata. Sahha uses reserved keys only; custom keys are stored and returned verbatim

Example Payload

json

{
	"id": "f3b1a8e0-4c5d-4e6f-9a8b-1c2d3e4f5a01",
	"profileId": "c9bf9e57-1685-4c89-bafb-ff5af830be8a",
	"accountId": "a3c1e8d2-4f6b-4a9c-8e7d-2b5f1c3a9e6b",
	"externalId": "user_12345",
	"type": "state",
	"category": "work",
	"name": "night_shift",
	"value": "12_hour",
	"source": "acme.workforce",
	"startDateTime": "2025-01-22T19:00:00+00:00",
	"endDateTime": "2025-01-23T07:00:00+00:00",
	"receivedAtUtc": "2025-01-23T07:05:02Z",
	"additionalProperties": {
		"role": "icu_nurse",
		"overtime": "false"
	}
}

Tag identity

A tag's identity is the tuple profileId + name + type + source + startDateTime, not the id. Re-uploading the same tuple—for example to close an open state with an endDateTime—updates the existing record, so you may receive more than one event for the same tag. Use the identity tuple for idempotency. See Tags for the full schema.

Data Log

Event

DataLogReceivedIntegrationEvent

Fired when raw health data is received from a user's device. Contains the original samples from HealthKit or Health Connect.

logType string

Log category: activity, sleep, heart, body, energy, exercise, blood, oxygen, temperature, device

dataType string

Specific data type (e.g., steps, heart_rate, sleep_stage_deep)

profileId string

UUID of the profile this data belongs to

accountId string

UUID of the account that owns the profile

externalId string

Your external identifier for the user

receivedAtUtc string

UTC timestamp when Sahha received the data

dataLogs DataLog[]

Array of individual data samples

Example Payload

json

{
	"logType": "activity",
	"dataType": "steps",
	"profileId": "c9bf9e57-1685-4c89-bafb-ff5af830be8a",
	"accountId": "a3c1e8d2-4f6b-4a9c-8e7d-2b5f1c3a9e6b",
	"externalId": "user_12345",
	"receivedAtUtc": "2025-01-22T14:30:00Z",
	"dataLogs": [
		{
			"id": "e5f6a7b8-c9d0-1234-ef56-789012345678",
			"parentId": null,
			"value": 1250,
			"unit": "count",
			"source": "iPhone 15 Pro",
			"recordingMethod": "RECORDING_METHOD_AUTOMATICALLY_RECORDED",
			"deviceType": "iPhone16,1",
			"startDateTime": "2025-01-22T09:00:00+00:00",
			"endDateTime": "2025-01-22T10:00:00+00:00",
			"additionalProperties": {}
		},
		{
			"id": "f6a7b8c9-d0e1-2345-f678-901234567890",
			"parentId": null,
			"value": 890,
			"unit": "count",
			"source": "Apple Watch",
			"recordingMethod": "RECORDING_METHOD_AUTOMATICALLY_RECORDED",
			"deviceType": "Watch7,1",
			"startDateTime": "2025-01-22T10:00:00+00:00",
			"endDateTime": "2025-01-22T11:00:00+00:00",
			"additionalProperties": {}
		}
	]
}

Object

DataLog

Each item in the dataLogs array contains:

id string

Unique identifier for this sample

parentId string nullable

Parent record ID for hierarchical data (e.g., exercise sessions)

value float

The recorded measurement value

unit string

Unit of measurement

source string

Device or app name that recorded the data

recordingMethod string

How the data was captured (automatic, manual, etc.)

deviceType string

Device model identifier

startDateTime string

When the measurement started (ISO 8601)

endDateTime string

When the measurement ended (ISO 8601)

additionalProperties map

Extra metadata specific to certain log types

Additional Properties

The additionalProperties field in DataLog contains metadata specific to certain log types. Log types not listed below (Activity, Body, Energy, Engagement, Sleep) have no additional properties.

Blood Logs

Property	Type	Description	Example
`BodyPosition`	string	Body position during measurement	`sitting`, `lying_down`
`MealType`	string	Type of meal consumed	`breakfast`, `lunch`, `dinner`
`MeasurementLocation`	string	Where on body measurement was taken	`finger`, `arm`
`RelationToMeal`	string	Timing relative to meal	`before_meal`, `after_meal`, `fasting`
`SpecimenSource`	string	Source of the blood specimen	`capillary`, `venous`

Device Logs

Property	Type	Description	Example
`DeviceScreenOn`	boolean	Whether the device screen was on	`true`, `false`

Exercise Logs

Property	Type	Description	Example
`TotalDistance`	float	Total distance covered	`5200.5` (meters)
`TotalEnergyBurned`	float	Total calories burned	`320.0` (kcal)

Heart Logs

Property	Type	Description	Example
`MeasurementLocation`	string	Where on body measurement was taken	`wrist`, `chest`, `finger`
`MotionContext`	string	User motion state when measured	`stationary`, `walking`, `running`

Oxygen Logs

Property	Type	Description	Example
`MeasurementMethod`	string	Method used to measure oxygen saturation	`pulse_oximetry`

Temperature Logs

Property	Type	Description	Example
`MeasurementLocation`	string	Where on body temperature was measured	`wrist`, `forehead`, `ear`

Support

Questions about webhook events? Reach out in the Slack community or contact support@sahha.ai .