La API de Google Health permite que tu aplicación reciba notificaciones en tiempo real cuando cambian los datos de salud de un usuario. En lugar de sondear los cambios, tu servidor recibe una solicitud HTTPS POST (webhook) en cuanto los datos están disponibles en la API de Google Health.
Tipos de datos admitidos
Las notificaciones de webhook son compatibles con los siguientes tipos de datos:
- Minutos en zona activa
- Altitud
- Grasa corporal
- Calorías en la zona de frecuencia cardíaca
- Variabilidad de la frecuencia cardíaca diaria
- Zonas de frecuencia cardíaca diarias
- Saturación de oxígeno diaria
- Frecuencia cardíaca en reposo diaria
- Derivaciones diarias de la temperatura del sueño
- Distancia
- Ejercicio
- Pisos
- Frecuencia cardíaca
- Sueño
- Pasos
- Total de calorías
- Peso
Las notificaciones se envían para estos tipos de datos solo cuando un usuario otorgó consentimiento para uno de los permisos correspondientes:
- Actividad, que abarca los tipos de datos de pasos, altitud, distancia y pisos:
https://www.googleapis.com/auth/googlehealth.activity_and_fitnesshttps://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
- Métricas de salud, que abarca el tipo de datos de peso:
https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurementshttps://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
- Sueño, que abarca el tipo de datos de sueño:
https://www.googleapis.com/auth/googlehealth.sleephttps://www.googleapis.com/auth/googlehealth.sleep.readonly
Cómo administrar los suscriptores
Para poder recibir notificaciones, debes registrar un suscriptor, que representa el extremo de notificación de tu aplicación. Puedes administrar los suscriptores
con la API de REST disponible en
projects.subscribers.
El extremo de tu suscriptor debe usar HTTPS (TLSv1.2+) y ser de acceso público.
Durante la creación y las actualizaciones de suscriptores, la API de Google Health realiza un desafío de verificación para garantizar que seas el propietario del URI del extremo. Si falla la verificación, las operaciones de creación y actualización de suscriptores fallan con una FailedPreconditionException.
Crea un suscriptor
Para registrar un nuevo suscriptor para tu proyecto, usa el
create
extremo. Debes proporcionar lo siguiente:
project-id: Es el número de proyecto en el que se creó la cuenta de servicio de webhook.subscriberId: Es un identificador único que proporcionas para el suscriptor. Este ID debe tener entre 4 y 36 caracteres, y coincidir con la expresión regular ([a-z]([a-z0-9-]{2,34}[a-z0-9])).endpointUri: Es la URL de destino para las notificaciones de webhook.subscriberConfigs: Son los tipos de datos para los que deseas recibir notificaciones y la política de suscripción para cada uno.endpointAuthorization: Es el mecanismo de autorización para tu extremo. Debe contener unsecretque proporciones. El valor desecretse envía en el encabezadoAuthorizationcon cada mensaje de notificación. Puedes usar este token para verificar que las solicitudes entrantes provengan de la API de Google Health. Por ejemplo, puedes configurarsecretcomoBearer R4nd0m5tr1ng123para la autenticación de portador oBasic dXNlcjpwYXNzd29yZA==para la autenticación básica.
En subscriberConfigs, debes configurar subscriptionCreatePolicy para cada tipo de datos. Configúralo como AUTOMATIC para usar suscripciones automáticas o MANUAL si deseas administrar las suscripciones de los usuarios por tu cuenta. Consulta
suscripciones automáticas y
suscripciones manuales para obtener más detalles sobre cada opción.
Solicitud
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"
}
}Respuesta
{
"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"
}
]
}Enumera los suscriptores
Usa el list extremo
para recuperar todos los suscriptores registrados para tu proyecto.
Solicitud
GET https://health.googleapis.com/v4/projects/project-id/subscribers
Respuesta
{
"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": {
"authorizationTokenSet": true
}
}
],
"totalSize": 1
}Actualiza un suscriptor
Usa el patch extremo
para actualizar un suscriptor en tu proyecto. Los campos que se pueden actualizar son endpointUri, subscriberConfigs y endpointAuthorization.
Para actualizar los campos, proporciona un parámetro de consulta updateMask y un cuerpo de solicitud. updateMask debe contener una lista separada por comas de los nombres de campo que deseas actualizar, con el uso de mayúsculas y minúsculas para los nombres de campo (por ejemplo, endpointUri). El cuerpo de la solicitud debe contener un objeto Subscriber parcial con los valores nuevos para los campos que deseas actualizar. Solo se actualizan los campos especificados en updateMask. Si proporcionas campos en el cuerpo de la solicitud que no están en updateMask, se ignoran.
Si actualizas endpointUri o endpointAuthorization, se realiza la verificación de extremos. Consulta Verificación de extremos para obtener más detalles.
Cuando actualizas subscriberConfigs, ten en cuenta que es un reemplazo completo, no una
combinación. Si subscriberConfigs se incluye en updateMask, todas las configuraciones almacenadas para ese suscriptor se reemplazarán por la lista proporcionada en el cuerpo de la solicitud. Para agregar o quitar una configuración, debes proporcionar el conjunto completo de configuraciones. Si actualizas otros campos y deseas conservar tus configuraciones actuales, omite subscriberConfigs de updateMask.
Solicitud
PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id?updateMask=endpointUri
{
"endpointUri": "https://myapp.com/new-webhooks/health"
}Respuesta
{
"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"
}
]
}Borra un suscriptor
Usa el delete
extremo para quitar un suscriptor de tu proyecto. Una vez borrado, el suscriptor ya no recibirá notificaciones.
Solicitud
DELETE https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id
Respuesta
Si la eliminación se realiza correctamente, se muestra un cuerpo de respuesta vacío con el estado HTTP `200 OK`.{}Verificación de extremos
Para garantizar la seguridad y la confiabilidad de la entrega de notificaciones, la API de Google Health realiza una verificación en dos pasos obligatoria cada vez que creas un suscriptor o actualizas su configuración de extremo (endpointUri o endpointAuthorization). Este proceso se realiza de forma síncrona durante la llamada a la API. El servicio envía dos solicitudes POST automáticas al URI de tu extremo,
con el User-Agent Google-Health-API-Webhooks-Verifier, con el cuerpo JSON
{"type": "verification"}.
- Protocolo de enlace autorizado: La primera solicitud se envía con el encabezado configurado
Authorization. Tu servidor debe responder con un estado200 OKo201 Created. - Desafío no autorizado: La segunda solicitud se envía sin credenciales.
Tu servidor debe responder con un estado
401 Unauthorizedo403 Forbidden.
Este protocolo de enlace confirma que tu extremo está activo y aplica la seguridad correctamente. Si falla alguno de los pasos, la solicitud a la API falla con un error FAILED_PRECONDITION. Solo después de que este protocolo de enlace se realice correctamente, se guardará y activará tu suscriptor para recibir notificaciones de datos de salud.
Rotación de claves
Si necesitas rotar claves para endpointAuthorization, sigue estos pasos:
- Configura tu extremo para que acepte valores
endpointAuthorizationantiguos y nuevos. - Actualiza la configuración del suscriptor con el nuevo valor
endpointAuthorizationmediante una solicitudpatchcon?updateMask=endpointAuthorization. - Configura tu extremo para que acepte solo el nuevo valor
endpointAuthorizationdespués de confirmar que el paso 2 se realizó correctamente.
Suscripciones del usuario
La API de Google Health te ayuda a administrar las suscripciones de los usuarios de manera eficiente, lo que reduce la necesidad de registro manual durante la incorporación de usuarios.
Suscripciones automáticas
Te recomendamos que uses suscripciones automáticas. Para habilitar esta función, configura subscriptionCreatePolicy como AUTOMATIC en tu subscriberConfigs para los tipos de datos específicos. Los dataTypes que especificas con una política AUTOMATIC son los mismos tipos de datos para los que la API de Google Health envía notificaciones, siempre que también se otorgue el consentimiento del usuario para esos tipos de datos.
Cuando un usuario otorga consentimiento de la aplicación para los permisos que corresponden a los tipos de datos con una política AUTOMATIC, la API de Google Health realiza un seguimiento automático y envía notificaciones para los tipos de datos que resultan de la intersección entre los tipos de datos obtenidos con consentimiento del usuario y los tipos de datos de configuración automática del suscriptor para ese usuario. Luego, las notificaciones se envían a tu extremo cada vez que ese usuario genera datos nuevos para esos tipos. Esto funciona para los usuarios que otorgan consentimiento antes o después de que crees el suscriptor. Las notificaciones no se reabastecen para los datos generados antes de que se creara el suscriptor.
Si un usuario revoca el consentimiento, se detendrán las notificaciones para los tipos de datos correspondientes. Google administra las suscripciones automáticas, y no se pueden enumerar ni borrar de forma individual. Se quitan solo cuando se borra el suscriptor superior.
Suscripciones manuales
Si prefieres administrar las suscripciones de cada usuario de forma manual, configura subscriptionCreatePolicy como MANUAL en subscriberConfigs. Con esta política, las suscripciones de los usuarios no se crean automáticamente. Esta funcionalidad se usará en el futuro cuando estén disponibles las APIs para administrar suscripciones manuales. Hasta que estas APIs estén disponibles, te recomendamos que uses suscripciones AUTOMATIC.
Notificaciones
Cuando cambian los datos de un usuario para un tipo de datos suscrito, la API de Google Health envía una solicitud HTTPS POST a la URL del extremo del suscriptor.
Formato de las notificaciones
La carga útil de la notificación es un objeto JSON que contiene detalles sobre el cambio de datos. Esto incluye el ID de usuario, el tipo de datos y los intervalos de tiempo, que puedes usar para consultar los datos actualizados.
{
"data": {
"version": "1",
"clientProvidedSubscriptionName": "subscription-name",
"healthUserId": "health-user-id",
"operation": "UPSERT",
"dataType": "steps",
"intervals": [
{
"physicalTimeInterval": {
"startTime": "2026-03-0B01: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"
}
}
]
}
}
El campo operation indica el tipo de cambio que activó la notificación:
UPSERT: Se envía para cualquier adición o modificación de datos.DELETE: Se envía cuando un usuario borra datos o cuando se quitan datos debido a un evento del sistema, como un usuario que revoca el permiso o borra su cuenta.
Te recomendamos que hagas que la lógica de manejo de notificaciones sea idempotente, en especial para las operaciones UPSERT, ya que los reintentos pueden provocar que se envíen notificaciones duplicadas.
El campo clientProvidedSubscriptionName es un identificador único. Para las suscripciones con una política MANUAL, este campo contiene el nombre de suscripción persistente proporcionado por el desarrollador que se especificó cuando se creó la suscripción.
Esto proporciona un ID estable para administrar suscripciones manuales. Para las suscripciones creadas con una política AUTOMATIC, la API de Google Health genera y asigna automáticamente un identificador único (un UUID aleatorio) a este campo para cada notificación. Incluir clientProvidedSubscriptionName para las políticas manuales y automáticas garantiza un formato de carga útil de notificación coherente en todos los tipos de suscripción.
healthUserId es un identificador de la API de Google Health para el usuario cuyos datos cambiaron. Si tu aplicación admite varios usuarios, es posible que recibas notificaciones para cualquier usuario que haya otorgado consentimiento a tu aplicación. Cuando recibas una notificación, usa healthUserId para identificar qué datos del usuario cambiaron, de modo que puedas usar sus credenciales de OAuth para consultar sus datos.
Para asignar las credenciales de OAuth de un usuario a su healthUserId, usa el
getIdentity extremo. Llama a este extremo con las credenciales de un usuario durante la incorporación del usuario para recuperar su healthUserId y almacenar esta asignación. Esta asignación no cambia con el tiempo, por lo que se puede almacenar en caché de forma indefinida. Para ver un ejemplo, consulta
Obtén el ID de usuario. Esto te permite seleccionar las credenciales de usuario correctas cuando consultas datos basados en el healthUserId en una notificación.
Responde a una notificación
Tu servidor debe responder a las notificaciones con un código de estado HTTP 204 No Content de inmediato. Para evitar los tiempos de espera, procesa la carga útil de la notificación de forma asíncrona después de enviar la respuesta. Si la API de Google Health recibe cualquier otro código de estado o se agota el tiempo de espera de la solicitud, vuelve a intentar enviar la notificación más tarde.
Ejemplo de Node.js (Express):
app.post('/webhook-receiver', (req, res) => {
// 1. Immediately acknowledge the notification
res.status(204).send();
// 2. Process the data asynchronously in the background
const notification = req.body;
setImmediate(() => {
console.log(`Update for user ${notification.data.healthUserId} of type ${notification.data.dataType}`);
// Trigger your data retrieval logic here
});
});
Estado y recuperación del suscriptor
Si el extremo de tu suscriptor deja de estar disponible o muestra un código de estado de error (cualquier valor que no sea 204), la API de Google Health almacena las notificaciones pendientes durante un máximo de 7 días y vuelve a intentar la entrega con retirada exponencial.
Una vez que tu extremo vuelva a estar en línea y responda con 204, la API entregará automáticamente el registro de mensajes almacenados. Las notificaciones de más de 7 días se descartan y no se pueden recuperar.