Google Health API позволяет вашему приложению получать уведомления, когда данные о здоровье пользователя меняются. Вместо того чтобы опрашивать сервер на предмет изменений, ваш сервер получает запрос HTTPS POST вебхука, как только данные становятся доступны в Google Health API.
Поддерживаемые типы данных
Уведомления вебхуков поддерживаются для следующих типов данных:
| Тип данных | Доступные операции |
Область действия |
|---|---|---|
|
Количество минут активности
dataType:
active-minutesfilter parameter: active_minutes
Тип записи: интервал.
Разрешение хранилища: 1 минута.
Совместимые устройства
|
list, reconcile, rollup, dailyRollup | .activity_and_fitness.readonly.activity_and_fitness.writeonly |
|
Минуты в зоне активности
dataType:
active-zone-minutesfilter parameter: active_zone_minutes
Тип записи: интервал.
Разрешение хранилища: 1 минута.
Совместимые устройства
|
list, reconcile, rollup, dailyRollup | .activity_and_fitness.readonly.activity_and_fitness.writeonly |
|
Уровень активности
|
список, сверка | .activity_and_fitness.readonly.activity_and_fitness.writeonly |
|
Altitude
|
list, reconcile, rollup, dailyRollup | .activity_and_fitness.readonly.activity_and_fitness.writeonly |
|
Уровень глюкозы в крови
dataType:
blood-glucosefilter parameter: blood_glucose
Тип записи: Sample.
|
list, get, reconcile, rollup, dailyRollup | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Жировая ткань
dataType:
body-fatfilter parameter: body_fat
Тип записи: Sample.
Совместимые устройства
|
list, get, reconcile, rollup, dailyRollup, create, update, batchDelete | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Калории в зоне ЧСС
dataType:
calories-in-heart-rate-zonefilter parameter: calories_in_heart_rate_zone
Тип записи: интервал.
Разрешение хранилища: 1 минута.
|
rollup, dailyRollup | .activity_and_fitness.readonly.activity_and_fitness.writeonly |
|
Ежедневная вариабельность сердечного ритма
dataType:
daily-heart-rate-variabilityfilter parameter: daily_heart_rate_variability
Тип записи: ежедневно.
Совместимые устройства
|
список, сверка | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Ежедневные зоны пульса
dataType:
daily-heart-rate-zonesfilter parameter: daily_heart_rate_zones
Тип записи: ежедневно.
|
список, сверка | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Ежедневный уровень кислорода в крови
dataType:
daily-oxygen-saturationfilter parameter: daily_oxygen_saturation
Тип записи: ежедневно.
Совместимые устройства
|
список, сверка | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Ежедневная частота дыхания
dataType:
daily-respiratory-ratefilter parameter: daily_respiratory_rate
Тип записи: ежедневно.
Совместимые устройства
|
список, сверка | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Ежедневная частота сердечных сокращений в покое
dataType:
daily-resting-heart-ratefilter parameter: daily_resting_heart_rate
Тип записи: ежедневно.
Совместимые устройства
|
список, сверка | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Ежедневные колебания температуры во время сна
dataType:
daily-sleep-temperature-derivationsfilter parameter: daily_sleep_temperature_derivations
Тип записи: ежедневно.
Поддержка вебхуков
Руководство по жизненным показателям
Руководство по сну
Руководство по температуре кожи
Совместимые устройства
|
список, сверка | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Расстояние
dataType:
distancefilter parameter: distance
Тип записи: интервал.
Разрешение хранилища: 1 минута.
Совместимые устройства
|
list, reconcile, rollup, dailyRollup | .activity_and_fitness.readonly.activity_and_fitness.writeonly |
|
Тренировка
dataType:
exercisefilter parameter: exercise
Тип записи: сеанс.
Совместимые устройства
|
list, get, reconcile, create, update, batchDelete | .activity_and_fitness.readonly.activity_and_fitness.writeonly |
|
Этажи
dataType:
floorsfilter parameter: floors
Тип записи: интервал.
Разрешение хранилища: 1 минута.
Совместимые устройства
|
reconcile, rollup, dailyRollup | .activity_and_fitness.readonly.activity_and_fitness.writeonly |
|
Пульс
dataType:
heart-ratefilter parameter: heart_rate
Тип записи: Sample.
Разрешение хранилища: 1 секунда.
Совместимые устройства
|
list, reconcile, rollup, dailyRollup | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Вариабельность сердечного ритма
dataType:
heart-rate-variabilityfilter parameter: heart_rate_variability
Тип записи: Sample.
Совместимые устройства
|
список, сверка | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Высота
|
list, get, reconcile, create, update, batchDelete | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Журнал потребления жидкости
|
list, get, reconcile, rollup, dailyRollup, create, update, batchDelete | .nutrition.readonly.nutrition.writeonly |
|
Журнал питания
dataType:
nutrition-logfilter parameter: nutrition_log
Тип записи: сеанс.
|
list, get, reconcile, rollup, dailyRollup, create, update, batchDelete | .nutrition.readonly.nutrition.writeonly |
|
Отчет о частоте дыхания во время сна
dataType:
respiratory-rate-sleep-summaryfilter parameter: respiratory_rate_sleep_summary
Тип записи: Sample.
Совместимые устройства
|
список, сверка | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
МПК при беге
dataType:
run-vo2-maxfilter parameter: run_vo2_max
Тип записи: Sample.
Совместимые устройства
|
list, reconcile, rollup, dailyRollup | .activity_and_fitness.readonly.activity_and_fitness.writeonly |
|
Период без активности
dataType:
sedentary-periodfilter parameter: sedentary_period
Тип записи: интервал.
Совместимые устройства
|
list, reconcile, rollup, dailyRollup | .activity_and_fitness.readonly.activity_and_fitness.writeonly |
|
Сон
dataType:
sleepfilter parameter: sleep
Тип записи: сеанс.
Совместимые устройства
|
list, get, reconcile, create, update, batchDelete | .sleep.readonly.sleep.writeonly |
|
Инструкции
dataType:
stepsfilter parameter: steps
Тип записи: интервал.
Разрешение хранилища: 1 минута.
Совместимые устройства
|
list, reconcile, rollup, dailyRollup | .activity_and_fitness.readonly.activity_and_fitness.writeonly |
|
Время в пульсовой зоне
dataType:
time-in-heart-rate-zonefilter parameter: time_in_heart_rate_zone
Тип записи: интервал.
Разрешение хранилища: 1 минута.
|
list, reconcile, rollup, dailyRollup | .activity_and_fitness.readonly.activity_and_fitness.writeonly |
|
Вес
dataType:
weightfilter parameter: weight
Тип записи: Sample.
Совместимые устройства
|
list, get, reconcile, rollup, dailyRollup, create, update, batchDelete | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
Области действия уведомлений
Уведомления отправляются для этих типов данных, только если пользователь дал согласие для одной из следующих областей действия:
- Активность – количество минут активности, шагов, этажей, высота над уровнем моря и пройденное расстояние.
https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonlyhttps://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
- Показатели здоровья, которые включают тип данных о весе:
https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonlyhttps://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.writeonly
- Сон – данные о сне:
https://www.googleapis.com/auth/googlehealth.sleep.readonlyhttps://www.googleapis.com/auth/googlehealth.sleep.writeonly
Сервисные аккаунты IAM
При настройке подписчиков для Google Health API мы рекомендуем использовать сервисный аккаунт IAM, хотя это и не обязательно. Сервисные аккаунты обеспечивают более высокий уровень безопасности для рабочих нагрузок приложений по сравнению со стандартными аккаунтами пользователей благодаря следующим функциям:
- Автоматизированные краткосрочные учетные данные. При подключении к среде выполнения Google Cloud (например, Compute Engine, Cloud Run или Google Kubernetes Engine) сервисные аккаунты автоматически получают и меняют безопасные краткосрочные учетные данные. Это позволяет избежать рисков, связанных с управлением и хранением постоянных статических ключей.
- Принцип минимальных привилегий. Сервисные аккаунты предоставляют выделенные идентификационные данные для рабочих нагрузок. Вы можете предоставить им только определенные разрешения, необходимые для управления конечными точками подписчиков, избегая более широкого доступа к вашим ресурсам Google Cloud.
- Независимость жизненного цикла. Сервисные аккаунты работают независимо от аккаунтов отдельных пользователей, поэтому кадровые изменения не влияют на стабильность аутентификации.
Как настроить сервисный аккаунт
Чтобы настроить аутентификацию приложения-подписчика с помощью сервисного аккаунта, выполните следующие действия:
- Создайте сервисный аккаунт. В консоли Google Cloud перейдите на страницу IAM и администрирования проекта и создайте сервисный аккаунт, управляемый пользователем.
- Предоставьте необходимые роли IAM. Назначьте сервисному аккаунту роли, необходимые для управления подписчиками в облачном проекте Google Cloud.
- Привяжите сервисный аккаунт к рабочей нагрузке. Настройте среду, в которой размещена логика подписчика, для запуска в качестве нового сервисного аккаунта.
Это позволит коду вашего приложения (например, клиентским библиотекам Google API) автоматически обнаруживать и использовать краткосрочные учетные данные сервисного аккаунта при вызове
projects.subscribersREST API.
Роли CPE
Чтобы управлять подписчиками или подписками Google Health API, необходимо предоставить соответствующую роль сервисному аккаунту, от имени которого выполняются вызовы API. В зависимости от необходимого уровня доступа назначьте одну из следующих ролей:
- Чтение Google Health API
- Редактор Google Health API
- Администратор Google Health API
Подробнее о ролях и разрешениях IAM в Google Health API…
Как управлять списком подписчиков
Чтобы получать уведомления, необходимо зарегистрировать подписчика, который представляет конечную точку уведомлений вашего приложения. Управлять подписчиками можно с помощью REST API, доступного по адресу projects.subscribers.
Рекомендуем создать по одному подписчику на каждый тип данных, особенно для типов с большим объемом данных, таких как steps. Это позволит ставить в очередь и доставлять частые обновления независимо от других типов данных. Несколько подписчиков в вашем проекте могут использовать один и тот же URL вебхука endpointUri.
Конечная точка подписчика должна использовать HTTPS (TLSv1.2+) и быть общедоступной.
При создании и обновлении подписчика Google Health API выполняет проверку, чтобы убедиться, что вы являетесь владельцем URI конечной точки. Если проверка не пройдена, то операции по созданию и обновлению подписчиков завершаются ошибкой FailedPreconditionException.
Создать подписчика
Чтобы зарегистрировать нового подписчика для проекта, используйте конечную точку create. Вам потребуется указать:
project-id: номер проекта, в котором был создан сервисный аккаунт вебхука.subscriberId– уникальный идентификатор, который вы предоставляете подписчику. Идентификатор должен содержать от 4 до 36 символов и соответствовать регулярному выражению ([a-z]([a-z0-9-]{2,34}[a-z0-9])).endpointUri– целевой URL для уведомлений вебхука.subscriberConfigs: типы данных, для которых вы хотите получать уведомления, и правила подписки для каждого из них.endpointAuthorization– механизм авторизации для конечной точки. Он должен содержать предоставленный вами объектsecret. Значениеsecretотправляется в заголовкеAuthorizationс каждым уведомлением. С помощью этого токена можно проверять, что входящие запросы поступают от Google Health API. Например, для аутентификации Bearer можно задать дляsecretзначениеBearer R4nd0m5tr1ng123, а для базовой аутентификации –Basic dXNlcjpwYXNzd29yZA==.
В subscriberConfigs необходимо задать subscriptionCreatePolicy для каждого типа данных. Установите значение AUTOMATIC, чтобы использовать автоматические подписки, или MANUAL, если вы хотите управлять подписками пользователей самостоятельно. Подробнее об автоматических и ручных подписках…
Эта конечная точка возвращает синхронный ресурс Operation, в котором для done задано значение true, а созданный ресурс Subscriber упакован в response.
Объект endpointAuthorization пропускает значение secret и задает для secretSet значение true.
Запрос
POST https://health.googleapis.com/v4/projects/project-id/subscribers?subscriberId=subscriber-id
{
"endpointUri": "https://myapp.com/webhooks/health",
"subscriberConfigs": [
{
"dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
"subscriptionCreatePolicy": "AUTOMATIC"
},
{
"dataTypes": ["sleep"],
"subscriptionCreatePolicy": "MANUAL"
}
],
"endpointAuthorization": {
"secret": "Bearer example-secret-token"
}
}Ответ
{
"name": "projects/project-id/operations/operation-id",
"metadata": {
"@type": "type.googleapis.com/google.devicesandservices.health.v4.CreateSubscriberMetadata"
},
"done": true,
"response": {
"@type": "type.googleapis.com/google.devicesandservices.health.v4.Subscriber",
"name": "projects/project-id/subscribers/subscriber-id",
"endpointUri": "https://myapp.com/webhooks/health",
"subscriberConfigs": [
{
"dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
"subscriptionCreatePolicy": "AUTOMATIC"
},
{
"dataTypes": ["sleep"],
"subscriptionCreatePolicy": "MANUAL"
}
],
"endpointAuthorization": {
"secretSet": true
},
"state": "ACTIVE"
}
}Список подписчиков
Используйте конечную точку list, чтобы получить список всех подписчиков, зарегистрированных в вашем проекте.
Запрос
GET https://health.googleapis.com/v4/projects/project-id/subscribers
Ответ
{
"subscribers": [
{
"name": "projects/project-id/subscribers/subscriber-id",
"endpointUri": "https://myapp.com/webhooks/health",
"subscriberConfigs": [
{
"dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
"subscriptionCreatePolicy": "AUTOMATIC"
},
{
"dataTypes": ["sleep"],
"subscriptionCreatePolicy": "MANUAL"
}
],
"endpointAuthorization": {
"secretSet": true
},
"state": "ACTIVE"
}
],
"totalSize": 1
}Обновить подписчика
Чтобы обновить подписчика в проекте, используйте конечную точку patch. Обновить можно поля endpointUri, subscriberConfigs и endpointAuthorization.
Чтобы обновить поля, укажите параметр запроса updateMask и тело запроса. В параметре updateMask необходимо указать список названий полей, которые нужно обновить, разделенный запятыми. Названия полей должны быть написаны в верблюжьем регистре (например, endpointUri). Тело запроса должно содержать частичный объект Subscriber с новыми значениями для полей, которые нужно обновить. Обновляются только поля, указанные в updateMask. Если в теле запроса указаны поля, которых нет в updateMask, они игнорируются.
Если вы обновите endpointUri или endpointAuthorization, будет выполнена проверка конечных точек. Подробнее о проверке конечных точек…
При обновлении subscriberConfigs обратите внимание, что это полная замена, а не объединение. Если subscriberConfigs включен в updateMask, все сохраненные конфигурации для этого подписчика перезаписываются списком, указанным в теле запроса. Чтобы добавить или удалить конфигурацию, необходимо указать полный набор конфигураций. Если вы обновляете другие поля и хотите сохранить текущие настройки, не указывайте subscriberConfigs в updateMask.
Как и create, эта конечная точка возвращает синхронный ресурс Operation, который содержит обновленный ресурс Subscriber, в котором для endpointAuthorization.secretSet задано значение true.
Запрос
PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id?updateMask=endpointUri
{
"endpointUri": "https://myapp.com/new-webhooks/health"
}Ответ
{
"name": "projects/project-id/operations/operation-id",
"done": true,
"response": {
"@type": "type.googleapis.com/google.devicesandservices.health.v4.Subscriber",
"name": "projects/project-id/subscribers/subscriber-id",
"endpointUri": "https://myapp.com/new-webhooks/health",
"subscriberConfigs": [
{
"dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
"subscriptionCreatePolicy": "AUTOMATIC"
},
{
"dataTypes": ["sleep"],
"subscriptionCreatePolicy": "MANUAL"
}
],
"endpointAuthorization": {
"secretSet": true
},
"state": "ACTIVE"
}
}Как удалить подписчика
Чтобы удалить подписчика из проекта, используйте конечную точку delete. После этого подписчик больше не будет получать уведомления.
Запрос
DELETE https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id
Ответ
{
"name": "projects/project-id/operations/operation-id",
"done": true,
"response": {
"@type": "type.googleapis.com/google.protobuf.Empty"
}
}Проверка конечных точек
Чтобы обеспечить безопасность и надежность доставки уведомлений, Google Health API выполняет обязательную двухэтапную аутентификацию при создании подписчика или обновлении конфигурации его конечной точки (endpointUri или endpointAuthorization). Этот процесс выполняется синхронно во время вызова API. Сервис отправляет два автоматических запроса POST на URI конечной точки, используя агент пользователя Google-Health-API-Webhooks с телом JSON {"type": "verification"}.
- Авторизованное рукопожатие. Первый запрос отправляется с настроенным вами заголовком
Authorization. Сервер должен возвращать статус200 OKили201 Created. - Unauthorized Challenge. Второй запрос отправляется без учетных данных.
Сервер должен возвращать статус
401 Unauthorizedили403 Forbidden.
Это подтверждает, что конечная точка активна и правильно обеспечивает безопасность. Если на любом из этих этапов произойдет сбой, запрос к API не будет выполнен и появится сообщение об ошибке FAILED_PRECONDITION. Только после успешного рукопожатия подписчик сохраняется и активируется для получения уведомлений о данных о здоровье.
Ротация ключей
Чтобы выполнить ротацию ключей для endpointAuthorization, выполните следующие действия:
- Настройте конечную точку так, чтобы она принимала как старые, так и новые значения
endpointAuthorization. - Обновите конфигурацию подписчика, указав новое значение
endpointAuthorization. Для этого отправьте запросpatchс параметром?updateMask=endpointAuthorization. - Настройте конечную точку так, чтобы она принимала только новое значение
endpointAuthorization, после того как убедитесь, что шаг 2 выполнен успешно.
Подписки пользователей
Google Health API помогает эффективно управлять подписками пользователей, снижая необходимость в ручной регистрации во время адаптации пользователей.
Автоматические подписки
Рекомендуем использовать автоматические подписки. Чтобы включить эту функцию, задайте для параметра subscriptionCreatePolicy значение AUTOMATIC в subscriberConfigs для определенных типов данных. Типы данных (dataTypes), которые вы указываете в правилах AUTOMATIC, совпадают с типами данных, для которых Google Health API отправляет уведомления, если согласие пользователя также предоставлено для этих типов данных.
Когда пользователь предоставляет приложению согласие на доступ к областям действия, соответствующим типам данных с правилом AUTOMATIC, Google Health API автоматически отслеживает и отправляет уведомления о типах данных, которые соответствуют как типам данных, на доступ к которым пользователь дал согласие, так и типам данных, указанным в конфигурации автоматического подписчика для этого пользователя. После этого на вашу конечную точку будут отправляться уведомления, когда пользователь генерирует новые данные этих типов. Это работает для пользователей, которые дают согласие до или после того, как вы создаете подписчика. Уведомления не заполняются данными, созданными до создания подписчика.
Если пользователь отзовет согласие, уведомления для соответствующих типов данных перестанут поступать. Автоматическими подписками управляет Google. Их нельзя просматривать или удалять по отдельности. Они удаляются только вместе с родительским подписчиком.
Подписки, оформленные вручную
Если для подписчика настроен MANUAL subscriptionCreatePolicy для определенных типов данных, вы должны явным образом создавать подписки для каждого пользователя и управлять ими. Подписка связывает определенного пользователя с конечной точкой подписчика для определенного набора типов данных:
- Чтобы создать подписку вручную для определенного
healthUserId, используйте конечную точкуcreate. Для этого метода у подписчика должно быть установлено значениеMANUALдляsubscriptionCreatePolicyв отношении запрашиваемых типов данных. - Чтобы обновить типы данных для существующей подписки пользователя, используйте конечную точку
patch. - Чтобы удалить подписку пользователя, используйте конечную точку
delete. После удаления конечная точка подписчика больше не будет получать уведомления для этого пользователя по связанным типам данных. - Чтобы получить список всех активных подписок, оформленных вручную, для определенного подписчика, используйте конечную точку
list. Результаты можно отфильтровать поuserилиdataType.
Чтобы получить список активных подписок, оформленных вручную, отправьте запрос GET к конечной точке list:
Запрос
GET https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id/subscriptions
Ответ
{
"subscriptions": [
{
"name": "projects/project-id/subscribers/subscriber-id/subscriptions/subscription-id",
"user": "users/health-user-id",
"dataTypes": [
"users/health-user-id/dataTypes/sleep"
]
}
]
}Уведомления
Когда данные пользователя меняются для подписанного типа данных, Google Health API отправляет запрос HTTPS POST на URL конечной точки подписчика.
Формат уведомления
Полезная нагрузка уведомления содержит сведения об изменении данных, включая идентификатор пользователя, тип данных и временные интервалы, которые можно использовать для запроса обновленных данных. Тела запросов push-уведомлений всегда доставляются в виде массива JSON ([...]), содержащего от 1 до 99 объектов уведомлений, даже если доставка содержит одно уведомление.
Когда срабатывает уведомление вебхука, Google Health API отправляет запрос HTTPS POST конечной точке подписчика в следующем формате:
Upsert (данные временного ряда)
POST https://your-endpoint-uri
Authorization: Bearer example-secret-token
GOOGLE-HEALTH-API-SIGNATURE: signature-value
Content-Type: application/json
[
{
"data": {
"version": "1",
"clientProvidedSubscriptionName": "subscription-name",
"healthUserId": "health-user-id",
"operation": "UPSERT",
"dataType": "steps",
"intervals": [
{
"physicalTimeInterval": {
"startTime": "2026-03-08T01:29:00Z",
"endTime": "2026-03-08T01:34:00Z"
},
"civilDateTimeInterval": {
"startDateTime": {
"date": {
"year": 2026,
"month": 3,
"day": 7
},
"time": {
"hours": 17,
"minutes": 29
}
},
"endDateTime": {
"date": {
"year": 2026,
"month": 3,
"day": 7
},
"time": {
"hours": 17,
"minutes": 34
}
}
},
"civilIso8601TimeInterval": {
"startTime": "2026-03-07T17:29:00",
"endTime": "2026-03-07T17:34:00"
}
}
]
}
}
]Удалить (данные временного ряда)
POST https://your-endpoint-uri
Authorization: Bearer example-secret-token
GOOGLE-HEALTH-API-SIGNATURE: signature-value
Content-Type: application/json
[
{
"data": {
"version": "1",
"clientProvidedSubscriptionName": "subscription-name",
"healthUserId": "health-user-id",
"operation": "DELETE",
"dataType": "steps",
"intervals": [
{
"physicalTimeInterval": {
"startTime": "2026-08-12T12:00:00Z",
"endTime": "2026-08-12T12:30:00Z"
},
"civilIso8601TimeInterval": {
"startTime": "2026-08-12T12:00:00",
"endTime": "2026-08-12T12:30:00"
}
}
]
}
}
]Удаление (идентифицируемые данные)
POST https://your-endpoint-uri
Authorization: Bearer example-secret-token
GOOGLE-HEALTH-API-SIGNATURE: signature-value
Content-Type: application/json
[
{
"data": {
"version": "1",
"clientProvidedSubscriptionName": "subscription-name",
"healthUserId": "health-user-id",
"operation": "DELETE",
"dataType": "sleep",
"intervals": [
{
"physicalTimeInterval": {
"startTime": "2026-08-12T22:00:00Z",
"endTime": "2026-08-13T06:00:00Z"
},
"civilIso8601TimeInterval": {
"startTime": "2026-08-12T22:00:00",
"endTime": "2026-08-13T06:00:00"
}
}
],
"recordId": "9875412"
}
}
]Пакетный перенос (несколько пользователей и типов данных)
POST https://your-endpoint-uri
Authorization: Bearer example-secret-token
GOOGLE-HEALTH-API-SIGNATURE: signature-value
Content-Type: application/json
[
{
"data": {
"version": "1",
"clientProvidedSubscriptionName": "auto-project-number-subscriber-id-WEBHOOK_DATA_TYPE_STEPS",
"healthUserId": "health-user-id-1",
"operation": "UPSERT",
"dataType": "steps",
"intervals": [
{
"physicalTimeInterval": {
"startTime": "2026-03-08T01:29:00Z",
"endTime": "2026-03-08T01:34:00Z"
},
"civilDateTimeInterval": {
"startDateTime": {
"date": {
"year": 2026,
"month": 3,
"day": 7
},
"time": {
"hours": 17,
"minutes": 29
}
},
"endDateTime": {
"date": {
"year": 2026,
"month": 3,
"day": 7
},
"time": {
"hours": 17,
"minutes": 34
}
}
},
"civilIso8601TimeInterval": {
"startTime": "2026-03-07T17:29:00",
"endTime": "2026-03-07T17:34:00"
}
}
]
}
},
{
"data": {
"version": "1",
"clientProvidedSubscriptionName": "auto-project-number-subscriber-id-WEBHOOK_DATA_TYPE_WEIGHT",
"healthUserId": "health-user-id-1",
"operation": "UPSERT",
"dataType": "weight",
"intervals": [
{
"physicalTimeInterval": {
"startTime": "2026-03-07T15:14:00Z",
"endTime": "2026-03-07T15:16:00Z"
},
"civilDateTimeInterval": {
"startDateTime": {
"date": {
"year": 2026,
"month": 3,
"day": 7
},
"time": {
"hours": 7,
"minutes": 14
}
},
"endDateTime": {
"date": {
"year": 2026,
"month": 3,
"day": 7
},
"time": {
"hours": 7,
"minutes": 16
}
}
},
"civilIso8601TimeInterval": {
"startTime": "2026-03-07T07:14:00",
"endTime": "2026-03-07T07:16:00"
}
}
]
}
},
{
"data": {
"version": "1",
"clientProvidedSubscriptionName": "auto-project-number-subscriber-id-WEBHOOK_DATA_TYPE_STEPS",
"healthUserId": "health-user-id-2",
"operation": "UPSERT",
"dataType": "steps",
"intervals": [
{
"civilDateTimeInterval": {
"startDateTime": {
"date": {
"year": 2026,
"month": 8,
"day": 20
},
"time": {
"hours": 0,
"minutes": 0
}
},
"endDateTime": {
"date": {
"year": 2026,
"month": 8,
"day": 21
},
"time": {
"hours": 0,
"minutes": 0
}
}
},
"civilIso8601TimeInterval": {
"startTime": "2026-08-20T00:00:00",
"endTime": "2026-08-21T00:00:00"
}
}
]
}
},
{
"data": {
"version": "1",
"clientProvidedSubscriptionName": "subscription-name",
"healthUserId": "health-user-id-2",
"operation": "UPSERT",
"dataType": "sleep",
"intervals": [
{
"physicalTimeInterval": {
"startTime": "2026-08-12T22:00:00Z",
"endTime": "2026-08-13T06:00:00Z"
},
"civilDateTimeInterval": {
"startDateTime": {
"date": {
"year": 2026,
"month": 8,
"day": 12
},
"time": {
"hours": 22,
"minutes": 0
}
},
"endDateTime": {
"date": {
"year": 2026,
"month": 8,
"day": 13
},
"time": {
"hours": 6,
"minutes": 0
}
}
},
"civilIso8601TimeInterval": {
"startTime": "2026-08-12T22:00:00",
"endTime": "2026-08-13T06:00:00"
}
}
],
"recordId": "9875412"
}
}
]Поле operation указывает на тип изменения, которое вызвало уведомление:
UPSERT– отправляется при любом добавлении или изменении данных.DELETE– отправляется, когда пользователь удаляет данные (например, удаляетdataPointsв приложении Fitbit или выполняет пакетное удаление с помощью API). Уведомления вебхука не отправляются для событий удаления на системном уровне, например когда пользователь отзывает разрешения приложения или удаляет свой аккаунт Fitbit.
Рекомендуем сделать логику обработки уведомлений идемпотентной, особенно для операций UPSERT, поскольку повторные попытки могут привести к отправке дублирующихся уведомлений.
Поле clientProvidedSubscriptionName – это уникальный идентификатор.
- Для подписок с правилами
MANUALэто поле содержит постоянное название подписки, указанное разработчиком при ее создании. Это позволяет получить стабильный идентификатор для управления подписками, оформленными вручную. - Для подписок, созданных с помощью правила
AUTOMATIC, Google Health API автоматически генерирует и назначает идентификатор в форматеauto-<project-number>-<subscriber-id>-<WEBHOOK_DATA_TYPE_TOKEN>, где:<project-number>– номер облачного проекта Google Cloud разработчика (например,362978535920).<subscriber-id>– идентификатор регистрации или имя подписчика (например,google-health-sync).<WEBHOOK_DATA_TYPE_TOKEN>– токен, представляющий определенный тип данных. Все возможные токены перечислены в словаре токенов типов данных вебхуков.
Включение clientProvidedSubscriptionName для правил, применяемых вручную и автоматически, обеспечивает согласованный формат полезной нагрузки уведомлений для всех типов подписок.
Сопоставление идентификаторов пользователей
healthUserId – это идентификатор Google Health API для пользователя, чьи данные изменились. Если ваше приложение поддерживает несколько пользователей, вы можете получать уведомления для любого пользователя, который предоставил согласие вашему приложению. Получив уведомление, используйте healthUserId, чтобы определить, чьи данные изменились, и запросить их с помощью учетных данных OAuth этого пользователя.
Чтобы сопоставить учетные данные OAuth пользователя с его healthUserId, используйте конечную точку getIdentity. Вызовите эту конечную точку с учетными данными пользователя во время его регистрации, чтобы получить его healthUserId, и сохраните это сопоставление. Это сопоставление не меняется со временем, поэтому его можно кешировать на неопределенный срок. Пример приведен в разделе Получение идентификатора пользователя. Это позволяет выбрать правильные учетные данные пользователя при запросе данных на основе healthUserId в уведомлении.
Временные интервалы
Массив intervals содержит один или несколько объектов, представляющих временные интервалы для измененных данных:
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
physicalTimeInterval |
object |
Нет | Физический интервал времени по UTC для измененных данных (формат YYYY-MM-DDTHH:MM:SSZ). Заполняется для показателей за день; опускается для ежедневных сводок и действий за весь день. |
civilDateTimeInterval |
object |
Да | Дата и временной интервал измененных данных по местному календарю без учета UTC или часовых поясов. |
civilIso8601TimeInterval |
object |
Да | Интервал гражданского (местного) времени, представленный в виде строки ISO 8601 (формат YYYY-MM-DDTHH:MM:SS) без UTC или смещений часового пояса. |
Для действий, выполняемых в течение всего дня, и ежедневных агрегированных данных поле physicalTimeInterval намеренно опущено в полезной нагрузке уведомления. Это связано с тем, что мероприятия на весь день группируются по номинальной гражданской дате, а физическая продолжительность времени может быть неточной при пересечении часовых поясов. При обработке мероприятий на весь день рекомендуется использовать поля civilDateTimeInterval или civilIso8601TimeInterval. Подробнее о том, как запрашивать эти данные с помощью фильтров гражданского времени начала интервала.
Ниже приведен пример полезной нагрузки уведомления для мероприятия, которое длится весь день. Поле physicalTimeInterval опущено.
[
{
"data": {
"version": "1",
"clientProvidedSubscriptionName": "auto-503461148219-lindasubscriber-WEBHOOK_DATA_TYPE_STEPS",
"healthUserId": "343864966078399341",
"operation": "UPSERT",
"dataType": "steps",
"intervals": [
{
"civilDateTimeInterval": {
"startDateTime": {
"date": {
"year": 2026,
"month": 7,
"day": 14
},
"time": {}
},
"endDateTime": {
"date": {
"year": 2026,
"month": 7,
"day": 15
},
"time": {}
}
},
"civilIso8601TimeInterval": {
"startTime": "2026-07-14T00:00:00",
"endTime": "2026-07-15T00:00:00"
}
}
]
}
}
]Словарь токенов типов данных вебхука
При использовании правила AUTOMATIC сгенерированный clientProvidedSubscriptionName содержит один из следующих суффиксов WEBHOOK_DATA_TYPE_*, написанных заглавными буквами, в зависимости от типа данных:
| Токен типа данных вебхука | Тип данных |
|---|---|
WEBHOOK_DATA_TYPE_ACTIVE_MINUTES |
active-minutes |
WEBHOOK_DATA_TYPE_ACTIVE_ZONE_MINUTES |
active-zone-minutes |
WEBHOOK_DATA_TYPE_ACTIVITY_LEVEL |
activity-level |
WEBHOOK_DATA_TYPE_ALTITUDE |
altitude |
WEBHOOK_DATA_TYPE_BLOOD_GLUCOSE |
blood-glucose |
WEBHOOK_DATA_TYPE_BODY_FAT |
body-fat |
WEBHOOK_DATA_TYPE_CALORIES_IN_HEART_RATE_ZONE |
calories-in-heart-rate-zone |
WEBHOOK_DATA_TYPE_DAILY_HEART_RATE_VARIABILITY |
daily-heart-rate-variability |
WEBHOOK_DATA_TYPE_DAILY_HEART_RATE_ZONES |
daily-heart-rate-zones |
WEBHOOK_DATA_TYPE_DAILY_OXYGEN_SATURATION |
daily-oxygen-saturation |
WEBHOOK_DATA_TYPE_DAILY_RESPIRATORY_RATE |
daily-respiratory-rate |
WEBHOOK_DATA_TYPE_DAILY_RESTING_HEART_RATE |
daily-resting-heart-rate |
WEBHOOK_DATA_TYPE_DAILY_SLEEP_TEMPERATURE_DERIVATIONS |
daily-sleep-temperature-derivations |
WEBHOOK_DATA_TYPE_DISTANCE |
distance |
WEBHOOK_DATA_TYPE_EXERCISE |
exercise |
WEBHOOK_DATA_TYPE_FLOORS |
floors |
WEBHOOK_DATA_TYPE_HEART_RATE |
heart-rate |
WEBHOOK_DATA_TYPE_HEART_RATE_VARIABILITY |
heart-rate-variability |
WEBHOOK_DATA_TYPE_HEIGHT |
height |
WEBHOOK_DATA_TYPE_HYDRATION_LOG |
hydration-log |
WEBHOOK_DATA_TYPE_NUTRITION_LOG |
nutrition-log |
WEBHOOK_DATA_TYPE_RESPIRATORY_RATE_SLEEP_SUMMARY |
respiratory-rate-sleep-summary |
WEBHOOK_DATA_TYPE_RUN_VO2_MAX |
run-vo2-max |
WEBHOOK_DATA_TYPE_SEDENTARY_PERIOD |
sedentary-period |
WEBHOOK_DATA_TYPE_SLEEP |
sleep |
WEBHOOK_DATA_TYPE_STEPS |
steps |
WEBHOOK_DATA_TYPE_TIME_IN_HEART_RATE_ZONE |
time-in-heart-rate-zone |
WEBHOOK_DATA_TYPE_WEIGHT |
weight |
WEBHOOK_DATA_TYPE_USER_DELETED |
user-deleted (системное событие) |
WEBHOOK_DATA_TYPE_USER_REVOKED_ACCESS |
user-revoked-access (системное событие) |
Агрегирование обновлений
Чтобы минимизировать сетевой трафик, Google Health API объединяет сообщения в пакеты.
Каждая push-доставка отправляет полезную нагрузку в виде массива JSON ([...]), содержащего от 1 до 99 объектов уведомлений, которые автоматически отправляются по мере их появления.
В одном пакете могут быть обновления для нескольких пользователей по нескольким типам данных, на которые оформлена подписка. Пример полезной нагрузки приведен в разделе Пакет (несколько пользователей и типов данных).
Реакция на уведомления
Ваш сервер должен проверять заголовок Authorization, обрабатывать синхронное подтверждение проверки конечной точки и немедленно подтверждать получение уведомлений об изменении данных (например, с помощью кода статуса HTTP 204 No Content). Чтобы избежать тайм-аутов, обрабатывайте полезную нагрузку уведомления асинхронно после отправки ответа.
Google Health API обрабатывает каждый пакет уведомлений на основе HTTP-ответа конечной точки:
| HTTP-ответ | Поведение при доставке |
|---|---|
Младше 400 лет (например, 200, 202, 204) |
Подтверждает доставку пакета уведомлений. |
408, 429, 5xx, тайм-аут запроса или недоступная конечная точка |
Повторяет попытку доставки с экспоненциальной выдержкой. Подробнее о статусе подписчика и восстановлении… |
Другие 4xx (например, 400, 401, 403, 404) |
Пакет уведомлений удаляется без возможности повторной отправки. |
Пример Node.js (Express):
app.post('/webhook-receiver', (req, res) => {
if (req.headers.authorization !== EXPECTED_SECRET) {
return res.status(401).send();
}
if (req.body && !Array.isArray(req.body) && req.body.type === 'verification') {
return res.status(200).send();
}
// 1. Immediately acknowledge the notification batch
res.status(204).send();
// 2. Group and coalesce batched notifications by (healthUserId, dataType)
// into a single [minStart, maxEnd) window before reconciling asynchronously
const notifications = Array.isArray(req.body) ? req.body : [];
setImmediate(async () => {
const windows = new Map();
for (const notification of notifications) {
const { healthUserId, dataType, intervals = [] } = notification.data || {};
if (!healthUserId || !dataType) {
continue;
}
const key = `${healthUserId}:${dataType}`;
for (const interval of intervals) {
const civil = interval.civilIso8601TimeInterval;
if (!civil || !civil.startTime || !civil.endTime) {
continue;
}
const current = windows.get(key);
if (!current) {
windows.set(key, {
healthUserId,
dataType,
minStart: civil.startTime,
maxEnd: civil.endTime,
});
} else {
if (civil.startTime < current.minStart) {
current.minStart = civil.startTime;
}
if (civil.endTime > current.maxEnd) {
current.maxEnd = civil.endTime;
}
}
}
}
for (const { healthUserId, dataType, minStart, maxEnd } of windows.values()) {
const filterType = dataType.replace(/-/g, '_');
const timeField = dataType === 'sleep'
? `${filterType}.interval.civil_end_time`
: dataType === 'weight'
? `${filterType}.sample_time.civil_time`
: `${filterType}.interval.civil_start_time`;
const filter = `${timeField} >= "${minStart}" AND ${timeField} < "${maxEnd}"`;
console.log(
`Reconcile ${dataType} for user ${healthUserId}: [${minStart}, ${maxEnd})`
);
// Call GET /v4/users/${healthUserId}/dataTypes/${dataType}/dataPoints:reconcile
// with query parameter `filter=${encodeURIComponent(filter)}`.
}
});
});
Сгруппируйте уведомления в каждом пакете по (healthUserId, dataType) и объедините их интервалы в одно окно [minStart, maxEnd), прежде чем вызывать конечную точку reconcile с фильтром для этого диапазона дат. Объединение позволяет избежать отправки избыточных запросов к API для пакетных доставок и reconcile автоматически удаляет дублирующиеся интервалы с подключенных устройств. Подробную информацию и примеры можно найти в статье Как получить согласованное представление данных за интервал.
Существует три распространенных стратегии обновления базы данных после получения уведомления об изменении данных:
- Постановка в очередь (рекомендуется). Входящие уведомления помещаются в очередь сообщений и обрабатываются по мере освобождения системных ресурсов.
- Немедленное получение. Настройте серверную часть так, чтобы она сразу вызывала Google Health API для получения обновленных данных и их сохранения в базе данных.
- Ленивые обновления. Помечайте записи в локальной базе данных пользователя как устаревшие и получайте обновленные данные из Google Health API только при следующем посещении пользователем вашего приложения.
Стратегия очередей позволяет оперативно обрабатывать данные, сохраняя при этом устойчивость к потоку уведомлений (например, если сбой в обслуживании приводит к одновременной доставке большого количества уведомлений). Вы можете обрабатывать эти очереди по расписанию с длинными интервалами (например, каждые три часа), чтобы экономить ресурсы, но пользователи обычно ожидают, что их данные будут обновляться быстрее.
Рекомендации
Чтобы обеспечить надежную и эффективную обработку обновлений данных, следуйте приведенным ниже рекомендациям.
- Подпишитесь на вебхуки и вызывайте Google Health API, когда получаете уведомление, а не опрашивайте конечные точки.
- Создайте по одному подписчику на каждый тип данных, особенно для типов данных с большим объемом, таких как
steps, чтобы изолировать очереди уведомлений по типам данных. Все ваши подписчики могут использовать один и тот же URL вебхукаendpointUri. - Google Health API доставляет уведомления вебхуков по мере возможности, поэтому некоторые уведомления могут задерживаться или не доставляться. Если для экрана или пути пользователя требуются актуальные данные, вызывайте Google Health API напрямую, даже если уведомление вебхука не получено. Например, когда пользователь потянет, чтобы обновить ваше приложение, запросите у Google Health API данные нужных типов.
- Полученные уведомления вебхука следует поместить в очередь и обрабатывать по отдельности в зависимости от ресурсов системы. Чтобы не перегружать конечную точку вебхука, подтверждайте запрос сразу.
- Отслеживайте временную метку, когда вы получаете уведомления, и запрашивайте данные за период с момента получения последнего уведомления до текущего времени. Это гарантирует, что у вас будут самые свежие данные, даже если вы пропустите уведомление. Временные метки в уведомлении помогут вам определить период времени, когда были внесены изменения в данные.
Подтверждение подписи
Чтобы обеспечить подлинность уведомлений вебхуков, необработанная полезная нагрузка JSON каждого исходящего уведомления подписывается закрытым ключом с помощью PublicKeySign Tink. При этом в HTTP-заголовке GOOGLE-HEALTH-API-SIGNATURE запроса указывается подпись в кодировке Base64. Эти ключи подписи автоматически меняются каждые 30 дней, а соответствующий официальный набор открытых ключей распространяется в виде JSON-файла по постоянному URL https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json.
Как подтвердить подпись
С помощью Tink (рекомендуется). Разработчики могут проверить подпись, используя примитив PublicKeyVerify в Tink. Получите набор открытых ключей по постоянному URL, создайте экземпляр примитива PublicKeyVerify с набором ключей и проверьте декодированный заголовок GOOGLE-HEALTH-API-SIGNATURE по необработанной полезной нагрузке JSON веб-хука.
Проверка вручную (без Tink). Если разработчики не хотят использовать Tink, они могут проверить подпись вручную, выполнив следующие действия:
- Декодирует заголовок
GOOGLE-HEALTH-API-SIGNATUREв формате Base64, чтобы отделить пятибайтовый префикс Tink (содержит однобайтовый префикс версии и четырехбайтовый идентификатор keyId) от фактической подписи в кодировке DER. - Получите набор ключей JSON по адресу https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json.
- Найдите ключ, соответствующий обработанному keyId, и декодируйте его поле value в формате Base64. Это поле содержит сериализованный буфер протокола EcdsaPublicKey.
- Извлеките координаты x и y с обратным порядком байтов (теги Protobuf 3 и 4) из этих двоичных данных.
- Создайте экземпляр стандартного открытого ключа ECDSA P-256 во встроенной криптографической библиотеке, используя извлеченные координаты x и y.
- Проверьте необработанную полезную нагрузку JSON веб-хука по извлеченной подписи DER с помощью алгоритма SHA-256.
Статус подписки и восстановление доступа
Если время ожидания конечной точки истекает, она становится недоступной или возвращает код статуса HTTP, который запускает повторные попытки, Google Health API сохраняет ожидающие уведомления в очереди доставки на срок до 24 часов и повторяет попытку доставки с экспоненциальной выдержкой. Подробную информацию о том, как API обрабатывает каждый HTTP-ответ, можно найти в разделе Ответ на уведомление.
Когда конечная точка восстановится и начнет возвращать код статуса ниже 400 (например, 204), API доставит оставшиеся сообщения из очереди. Уведомления, полученные более 24 часов назад, удаляются без возможности восстановления.
Распространенные ошибки
| Код ошибки | Сообщение | Описание | Рекомендация |
|---|---|---|---|
| 400 Bad Request | Недопустимый номер проекта в названии ресурса. | При удалении или обновлении подписчика с использованием идентификатора проекта Google Cloud в URL запроса вместо номера проекта. Это относится к подпискам на вебхуки, использующим конечную точку projects.subscribers. |
В URL запроса используйте номер проекта Google Cloud, а не его идентификатор. |
| 403 Forbidden | У звонящего нет нужных прав | При создании или получении списка подписчиков с использованием идентификатора проекта Google Cloud в URL запроса вместо номера проекта. Это относится к подпискам на вебхуки, использующим конечную точку projects.subscribers. |
В URL запроса используйте номер проекта Google Cloud, а не его идентификатор. |