Start Free Trial

Webhook Events

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
}

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 .

Previous
Webhooks
Next
Scores