Suscripciones a webhooks

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){:target="_blank" class="external"} 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
  • Nivel de actividad
  • Altitud
  • Glucemia
  • 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 respiratoria diaria
  • Frecuencia cardíaca en reposo diaria
  • Derivaciones diarias de la temperatura del sueño
  • Distancia
  • Ejercicio
  • Pisos
  • Frecuencia cardíaca
  • Variabilidad de la frecuencia cardíaca
  • Altura
  • Registro de hidratación
  • Registro de nutrición
  • Resumen de la frecuencia respiratoria durante el sueño
  • VO2 máx. en carreras
  • Período sedentario
  • Sueño
  • Pasos
  • Tiempo en la zona de frecuencia cardíaca
  • Total de calorías
  • Peso

Las notificaciones se envían para estos tipos de datos solo cuando un usuario otorgó su 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_fitness.readonly
    • https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
  • Métricas de salud, que abarca el tipo de datos de peso:
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.writeonly
  • Sueño, que abarca el tipo de datos de sueño:
    • https://www.googleapis.com/auth/googlehealth.sleep.readonly
    • https://www.googleapis.com/auth/googlehealth.sleep.writeonly

Cuentas de servicio de IAM

Si bien no es obligatorio, te recomendamos que uses una cuenta de servicio de IAM cuando configures suscriptores para la API de Google Health. Las cuentas de servicio proporcionan mejor seguridad para las cargas de trabajo de las aplicaciones en comparación con las cuentas de usuario estándar a través de las siguientes funciones:

  • Credenciales automáticas de corta duración: Cuando se adjuntan a un entorno de ejecución de Google Cloud (como Compute Engine, Cloud Run o Google Kubernetes Engine), las cuentas de servicio obtienen y rotan automáticamente credenciales seguras de corta duración. Esto elimina los riesgos de administrar y almacenar claves estáticas persistentes.
  • Principio de privilegio mínimo: Las cuentas de servicio proporcionan identidades dedicadas para las cargas de trabajo. Puedes otorgarles solo los permisos específicos necesarios para administrar los extremos de suscriptores, lo que evita un acceso más amplio a tus recursos de Google Cloud.
  • Independencia del ciclo de vida: Las cuentas de servicio operan de forma independiente de la cuenta de cualquier usuario individual, lo que garantiza que los cambios de personal no afecten la estabilidad de la autenticación a largo plazo.

Configurar una cuenta de servicio

Para configurar tu aplicación de suscriptor para que se autentique con una cuenta de servicio, haz lo siguiente:

  1. Crea una cuenta de servicio: En la consola de Google Cloud, navega a la página IAM y administración de tu proyecto para crear una cuenta de servicio nueva administrada por el usuario.
  2. Otorga las funciones de IAM necesarias: Asigna a la cuenta de servicio las funciones adecuadas necesarias para administrar los suscriptores en tu proyecto de Google Cloud.
  3. Adjunta la cuenta de servicio a tu carga de trabajo: Configura el entorno que aloja tu lógica de suscriptor para que se ejecute como la cuenta de servicio nueva. Esto permite que el código de tu aplicación (como las bibliotecas cliente de la API de Google) detecte y use automáticamente las credenciales de corta duración de la cuenta de servicio cuando llames a la API de REST de projects.subscribers.

Funciones de CPE

Para administrar los suscriptores o las suscripciones de la API de Google Health, debes otorgar la función adecuada a la cuenta de servicio suplantada que realiza las llamadas a la API. Según el nivel de acceso necesario, asigna una de las siguientes funciones:

  • Google Health API Read
  • Editor de la API de Google Health
  • Administrador de la API de Google Health

Obtén más información sobre las funciones y los permisos de IAM de la API de Google Health.

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 suscriptor nuevo 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 un secret que proporciones. El valor de secret se envía en el encabezado Authorization con 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 configurar secret como Bearer R4nd0m5tr1ng123 para la autenticación de portador o Basic 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 actualices subscriberConfigs, ten en cuenta que es un reemplazo completo, no una combinación. Si subscriberConfigs se incluye en updateMask, todos los parámetros de configuración almacenados 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 usuario-agente 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 estado 200 OK o 201 Created.
  • Desafío no autorizado: La segunda solicitud se envía sin credenciales. Tu servidor debe responder con un estado 401 Unauthorized o 403 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 las claves de endpointAuthorization, sigue estos pasos:

  1. Configura tu extremo para que acepte valores endpointAuthorization antiguos y nuevos.
  2. Actualiza la configuración del suscriptor con el nuevo valor endpointAuthorization mediante una solicitud patch con ?updateMask=endpointAuthorization.
  3. Configura tu extremo para que acepte solo el nuevo valor endpointAuthorization despué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 del suscriptor automático 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 su 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 tu suscriptor está configurado con una subscription_create_policy MANUAL para tipos de datos específicos, debes crear y administrar suscripciones de forma explícita para cada usuario. Una suscripción vincula un usuario específico al extremo de tu suscriptor para un conjunto definido de tipos de datos. Los desarrolladores pueden usar APIs específicas para lo siguiente:

  • Crear suscripciones (manuales) por healthUserId: Crea una suscripción nueva para un usuario específico. Este método requiere que el suscriptor tenga un SubscriptionCreatePolicy configurado como MANUAL para los tipos de datos solicitados.
  • Actualizar la suscripción (manual): Actualiza los tipos de datos para una suscripción de usuario existente.
  • Borrar la suscripción (manual): Borra una suscripción de usuario específica. Una vez borrado, el extremo de tu suscriptor ya no recibirá notificaciones para este usuario para los tipos de datos asociados.
  • Enumerar suscripciones (manuales): Enumera todas las suscripciones activas para un suscriptor determinado. Puedes filtrar los resultados por usuario o tipo de datos.

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-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"
        }
      }
    ]
  }
}

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.

Te recomendamos que hagas que tu lógica de control 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 su 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 agotados, 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
    });
});

Verificación de firma

Para garantizar la autenticidad de las notificaciones de Webhooks, la carga útil JSON sin procesar de cada notificación de webhook saliente se firma con una clave privada mediante PublicKeySign de Tink, lo que proporciona la firma codificada en Base64 en el encabezado HTTP GOOGLE-HEALTH-API-SIGNATURE de la solicitud. Estas claves de firma se rotan automáticamente cada 30 días, y el conjunto de claves públicas oficiales correspondiente se distribuye como un archivo JSON en la URL permanente https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json.

Cómo verificar la firma

Usa Tink (recomendado): Los desarrolladores pueden verificar la firma con la primitiva PublicKeyVerify de Tink. Recupera el conjunto de claves públicas de la URL permanente, crea una instancia de la primitiva PublicKeyVerify con el conjunto de claves y verifica el encabezado GOOGLE-HEALTH-API-SIGNATURE decodificado con la carga útil JSON de webhook sin procesar.

Verificación manual (sin Tink): Si los desarrolladores deciden no usar Tink, pueden verificar la firma de forma manual siguiendo estos pasos:

  1. Decodifica en Base64 el encabezado GOOGLE-HEALTH-API-SIGNATURE para separar el prefijo Tink de 5 bytes (que contiene un prefijo de versión de 1 byte y un keyId de 4 bytes) de la firma codificada en DER real.
  2. Recupera el conjunto de claves JSON de https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json.
  3. Ubica la clave que coincida con el keyId analizado y decodifica en Base64 su campo de valor, que contiene un búfer de protocolo EcdsaPublicKey serializado.
  4. Extrae las coordenadas x e y de orden de bytes grande (etiquetas Protobuf 3 y 4) de esta carga útil binaria.
  5. Crea una instancia de una clave pública ECDSA P-256 estándar en una biblioteca de criptografía integrada con las coordenadas x e y extraídas.
  6. Verifica la carga útil JSON de webhook sin procesar con la firma DER extraída mediante el algoritmo SHA-256.

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 por hasta 7 días y vuelve a intentar la entrega con una retirada exponencial.

Una vez que tu extremo vuelva a estar en línea y responda con 204, la API entregará automáticamente el backlog de mensajes almacenados. Las notificaciones de más de 7 días se descartan y no se pueden recuperar.

Errores comunes

Código de error Mensaje Descripción Recomendación
400 Bad Request Número de proyecto no válido en el nombre del recurso Cuando borras o actualizas un suscriptor con el ID del proyecto de Google Cloud en la URL de la solicitud en lugar del número de proyecto. Esto se aplica a las suscripciones de webhook que usan el extremo projects.subscribers. Usa el número de tu proyecto de Google Cloud en la URL de la solicitud, no el ID del proyecto.
403 Forbidden El emisor no tiene permiso Cuando creas o enumeras suscriptores con el ID de tu proyecto de Google Cloud en la URL de la solicitud en lugar del número de proyecto. Esto se aplica a las suscripciones de webhook que usan el extremo projects.subscribers. Usa el número de tu proyecto de Google Cloud en la URL de la solicitud, no el ID del proyecto.

Anterior
Vínculos universales y de aplicaciones
Siguiente
Solución de problemas