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) en cuanto hay datos disponibles en la API de Google Health.

Tipos de datos admitidos

Se admiten las notificaciones de webhook para los siguientes tipos de datos:

  • Pasos
  • Altitud
  • Distancia
  • Pisos
  • Peso
  • Sueño

Las notificaciones para estos tipos de datos solo se envían cuando un usuario otorgó consentimiento para uno de los siguientes alcances correspondientes:

  • Actividad, que abarca los tipos de datos de pasos, altitud, distancia y pisos:
    • https://www.googleapis.com/auth/googlehealth.activity_and_fitness
    • https://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_measurements
    • https://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.sleep
    • https://www.googleapis.com/auth/googlehealth.sleep.readonly

Cómo administrar los suscriptores

Antes de poder recibir notificaciones, debes registrar un suscriptor, que representa el extremo de notificaciones de tu aplicación. Puedes administrar suscriptores con la API de REST disponible en projects.subscribers.

Tu extremo de 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 propietario del URI del extremo. Si falla la verificación, las operaciones de creación y actualización de suscriptores fallarán con un FailedPreconditionException.

Crea un suscriptor

Para registrar un suscriptor nuevo para tu proyecto, usa el extremo create. Debes proporcionar lo siguiente:

  • 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 authorization_token que proporciones. El valor de authorization_token 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 establecer authorization_token en Bearer R4nd0m5tr1ng123 para la autenticación de portador o en Basic dXNlcjpwYXNzd29yZA== para la autenticación básica.
  • 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])).

En subscriberConfigs, debes establecer subscriptionCreatePolicy para cada tipo de datos. Establécelo en AUTOMATIC para usar suscripciones automáticas o en MANUAL si planeas administrar las suscripciones de los usuarios por tu cuenta. Consulta las suscripciones automáticas y las 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": {
    "authorization_token": "Bearer example-secret-token"
  }
}

Respuesta

{
  "name": "projects/project-id/subscribers/subscriber-id",
  "endpointUri": "https://myapp.com/webhooks/health",
  "state": "ACTIVE",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ],
  "endpointAuthorization": {
    "authorizationTokenSet": true
  }
}

Enumera los suscriptores

Usa el extremo list para recuperar todos los suscriptores registrados en 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",
      "state": "ACTIVE",
      "subscriberConfigs": [
        {
          "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
          "subscriptionCreatePolicy": "AUTOMATIC"
        },
        {
          "dataTypes": ["sleep"],
          "subscriptionCreatePolicy": "MANUAL"
        }
      ],
      "endpointAuthorization": {
        "authorizationTokenSet": true
      }
    }
  ],
  "nextPageToken": ""
}

Actualiza un suscriptor

Usa el extremo patch para actualizar un suscriptor en tu proyecto. Los campos que se pueden actualizar son endpointUri, subscriberConfigs y endpointAuthorization.

Para actualizar campos, proporciona un parámetro de consulta updateMask y un cuerpo de solicitud. El parámetro updateMask debe contener una lista separada por comas de los nombres de los campos que deseas actualizar, con el formato camel case para los nombres de los campos (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 ignorarán.

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 se trata de un reemplazo completo, no de una combinación. Si subscriberConfigs se incluye en updateMask, todas las configuraciones almacenadas para ese suscriptor se reemplazan 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",
  "state": "ACTIVE",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ],
  "endpointAuthorization": {
    "authorizationTokenSet": true
  }
}

Verificación de extremos

Para garantizar la seguridad y la confiabilidad de la entrega de notificaciones, la API de Google Health realiza un protocolo de enlace de verificación obligatoria de dos pasos cada vez que creas un suscriptor o actualizas la configuración de su 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 automatizadas al URI de tu extremo, con el User-Agent Google-Health-API-Webhooks-Verifier y el cuerpo JSON {"type": "verification"}.

  • Apertura autorizada: La primera solicitud se envía con el encabezado Authorization configurado. 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 handshake confirma que tu extremo está activo y que aplica la seguridad correctamente. Si falla alguno de los pasos, la solicitud a la API fallará con un error FAILED_PRECONDITION. Solo después de que se complete este proceso de enlace, se guardará tu suscriptor y se activará 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 tanto antiguos como nuevos.
  2. Actualiza la configuración del suscriptor con el nuevo valor de endpointAuthorization usando una solicitud patch con ?updateMask=endpointAuthorization.
  3. Configura tu extremo para que solo acepte el nuevo valor de endpointAuthorization después de confirmar que el paso 2 se realizó correctamente.

Cómo borrar un suscriptor

Usa el extremo delete para quitar un suscriptor de tu proyecto. Una vez que se borre, 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 devuelve un cuerpo de respuesta vacío con el estado HTTP "200 OK". 
{}

Suscripciones de usuarios

La API de Google Health te ayuda a administrar las suscripciones de los usuarios de manera eficiente, lo que reduce la necesidad de realizar registros manuales durante la incorporación de usuarios.

Suscripciones automáticas

Recomendamos usar suscripciones automáticas. Para habilitar esta función, establece subscriptionCreatePolicy en AUTOMATIC en tu subscriberConfigs para los tipos de datos específicos. El objeto dataTypes que especificas con una política de 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 tipos de datos con una política de AUTOMATIC, la API de Google Health automáticamente hace un seguimiento de los tipos de datos que resultan de la intersección entre los tipos de datos para los que el usuario otorgó consentimiento y los tipos de datos de configuración del suscriptor automático para ese usuario, y envía notificaciones sobre ellos. Luego, se envían notificaciones a tu extremo cada vez que ese usuario genera datos nuevos para esos tipos. Esto funciona para los usuarios que otorgan el 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, por lo que no se pueden enumerar ni borrar de forma individual. Solo se quitan cuando se borra el suscriptor principal.

Suscripciones manuales

Si prefieres administrar las suscripciones de cada usuario de forma manual, establece subscriptionCreatePolicy en 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 POST de HTTPS 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 modificación o adición de datos.
  • DELETE: Se envía cuando un usuario borra datos o cuando se quitan datos debido a un evento del sistema, como cuando un usuario revoca el permiso o borra su cuenta.

Te recomendamos que hagas que tu lógica de control de notificaciones sea idempotente, en especial para las operaciones de UPSERT, ya que los reintentos pueden provocar que se envíen notificaciones duplicadas.

El campo clientProvidedSubscriptionName es un identificador único. En el caso de las suscripciones con una política de MANUAL, este campo contiene el nombre persistente de la suscripción proporcionado por el desarrollador que se especificó cuando se creó la suscripción. Esto proporciona un ID estable para administrar suscripciones manuales. En el caso de las suscripciones creadas con una política de 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.

El 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 los datos del usuario que 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 extremo getIdentity. 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 Cómo obtener el ID de usuario. Esto te permite seleccionar las credenciales de usuario correctas cuando consultas datos según 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 de suscriptor y recuperación

Si tu endpoint de 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 una espera 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 con más de 7 días de antigüedad se descartan y no se pueden recuperar.

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