Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Abonnements aux webhooks

L'API Google Health permet à votre application de recevoir des notifications en temps réel lorsque les données de santé d'un utilisateur changent. Au lieu d'interroger les modifications, votre serveur reçoit une requête HTTPS POST (webhook){:target="_blank" class="external"} dès que des données sont disponibles dans l'API Google Health.

Types de données acceptés

Les notifications de webhook sont compatibles avec les types de données suivants :

Minutes en zone active
Niveau d'activité
Altitude
Taux de glycémie
Masse grasse
Calories dans la zone de fréquence cardiaque
Variabilité de la fréquence cardiaque quotidienne
Zones de fréquence cardiaque quotidiennes
Saturation en oxygène quotidienne
Fréquence respiratoire quotidienne
Fréquence cardiaque au repos quotidienne
Dérivations de la température pendant le sommeil quotidiennes
Distance
Exercice
Étages
Fréquence cardiaque
Variabilité de la fréquence cardiaque
Hauteur
Journal d'hydratation
Journal de nutrition
Résumé du sommeil (fréquence respiratoire)
VO2 max de la course
Période sédentaire
Sommeil
Étapes
Temps dans la zone de fréquence cardiaque
Total des calories
Poids

Les notifications ne sont envoyées pour ces types de données que lorsqu'un utilisateur a donné son consentement pour l'un des champs d'application correspondants :

Activité, qui couvre les types de données "Étapes", "Altitude", "Distance" et "Étages" :
- https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
- https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
Indicateurs de santé, qui couvre le type de données "Poids" :
- https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
- https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.writeonly
Sommeil, qui couvre le type de données "Sommeil" :
- https://www.googleapis.com/auth/googlehealth.sleep.readonly
- https://www.googleapis.com/auth/googlehealth.sleep.writeonly

Comptes de service IAM

Bien que cela ne soit pas obligatoire, nous vous recommandons d'utiliser un compte de service IAM lorsque vous configurez des abonnés pour l'API Google Health. Les comptes de service offrent une meilleure sécurité pour les charges de travail des applications que les comptes utilisateur standards grâce aux fonctionnalités suivantes :

Identifiants automatisés à courte durée de vie : lorsqu'ils sont associés à un environnement d'exécution Google Cloud (tel que Compute Engine, Cloud Run ou Google Kubernetes Engine), les comptes de service obtiennent et font pivoter automatiquement des identifiants sécurisés à courte durée de vie. Cela élimine les risques liés à la gestion et au stockage de clés statiques persistantes.
Principe du moindre privilège : les comptes de service fournissent des identités dédiées aux charges de travail. Vous ne pouvez leur accorder que les autorisations spécifiques nécessaires pour gérer les points de terminaison des abonnés, ce qui évite un accès plus large à vos ressources Google Cloud.
Indépendance du cycle de vie : les comptes de service fonctionnent indépendamment du compte d'un utilisateur individuel, ce qui garantit que les changements de personnel n'ont pas d'incidence sur la stabilité de l'authentification à long terme.

Configurer un compte de service

Pour configurer votre application abonnée afin qu'elle s'authentifie à l'aide d'un compte de service :

Créez un compte de service : dans la console Google Cloud, accédez à la page IAM et administration de votre projet pour créer un compte de service géré par l'utilisateur.
Attribuez les rôles IAM nécessaires : attribuez au compte de service les rôles appropriés requis pour gérer les abonnés de votre projet Google Cloud.
Associez le compte de service à votre charge de travail : configurez l'environnement qui héberge votre logique d'abonné pour qu'il s'exécute en tant que nouveau compte de service. Cela permet au code de votre application (tel que les bibliothèques clientes de l'API Google) de détecter et d'utiliser automatiquement les identifiants à courte durée de vie du compte de service lors de l'appel de l'API REST projects.subscribers.

Rôles CPE

Pour gérer les abonnés ou les abonnements de l'API Google Health, vous devez accorder le rôle approprié au compte de service dont l'identité est empruntée qui effectue les appels d'API. En fonction du niveau d'accès requis, attribuez l'un des rôles suivants :

Lecture de l'API Google Health
Éditeur de l'API Google Health
Administrateur de l'API Google Health

En savoir plus sur les rôles et autorisations IAM de l'API Google Health.

Gérer vos abonnés

Pour recevoir des notifications, vous devez enregistrer un abonné, qui représente le point de terminaison de notification de votre application. Vous pouvez gérer les abonnés à l'aide de l'API REST disponible sur projects.subscribers.

Le point de terminaison de votre abonné doit utiliser HTTPS (TLSv1.2+) et être accessible au public. Lors de la création et de la mise à jour des abonnés, l'API Google Health effectue un défi de validation pour s'assurer que vous êtes propriétaire de l'URI du point de terminaison. Si la validation échoue, les opérations de création et de mise à jour des abonnés échouent avec une FailedPreconditionException.

Créer un abonné

Pour enregistrer un nouvel abonné pour votre projet, utilisez le create point de terminaison. Vous devez fournir les éléments suivants :

project-id : numéro du projet dans lequel le compte de service de webhook a été créé.
subscriberId: identifiant unique que vous fournissez pour l'abonné. Cet ID doit comporter entre 4 et 36 caractères et correspondre à l'expression régulière ([a-z]([a-z0-9-]{2,34}[a-z0-9])).
endpointUri : URL de destination des notifications de webhook.
subscriberConfigs: types de données pour lesquels vous souhaitez recevoir des notifications, et la règle d'abonnement pour chacun.
endpointAuthorization : mécanisme d'autorisation pour votre point de terminaison. Il doit contenir un secret que vous fournissez. La valeur de secret est envoyée dans l'en-tête Authorization avec chaque message de notification. Vous pouvez utiliser ce jeton pour vérifier que les requêtes entrantes proviennent de l'API Google Health. Par exemple, vous pouvez définir secret sur Bearer R4nd0m5tr1ng123 pour l'authentification Bearer ou sur Basic dXNlcjpwYXNzd29yZA== pour l'authentification de base.

Dans subscriberConfigs, vous devez définir subscriptionCreatePolicy pour chaque type de données. Définissez-le sur AUTOMATIC pour utiliser les abonnements automatiques ou sur MANUAL si vous prévoyez de gérer vous-même les abonnements des utilisateurs. Pour en savoir plus sur chaque option, consultez Abonnements automatiques et Abonnements manuels.

Requête

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

Réponse

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

Répertorier les abonnés

Utilisez le list point de terminaison pour récupérer tous les abonnés enregistrés pour votre projet.

Requête

GET https://health.googleapis.com/v4/projects/project-id/subscribers

Réponse

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

Modifier un abonné

Utilisez le patch point de terminaison pour modifier un abonné dans votre projet. Les champs qui peuvent être modifiés sont endpointUri, subscriberConfigs et endpointAuthorization.

Pour modifier des champs, fournissez un paramètre de requête updateMask et un corps de requête. updateMask doit contenir une liste de noms de champs séparés par une virgule que vous souhaitez modifier, en utilisant la casse mixte pour les noms de champs (par exemple, endpointUri). Le corps de la requête doit contenir un objet Subscriber partiel avec les nouvelles valeurs des champs que vous souhaitez modifier. Seuls les champs spécifiés dans updateMask sont modifiés. Si vous fournissez des champs dans le corps de la requête qui ne figurent pas dans updateMask, ils sont ignorés.

Si vous modifiez endpointUri ou endpointAuthorization, la validation des points de terminaison est effectuée. Pour en savoir plus, consultez Validation des points de terminaison.

Lorsque vous modifiez subscriberConfigs, notez qu'il s'agit d'un remplacement complet, et non d'une fusion. Si subscriberConfigs est inclus dans updateMask, toutes les configurations stockées pour cet abonné sont remplacées par la liste fournie dans le corps de la requête. Pour ajouter ou supprimer une configuration, vous devez fournir l'ensemble complet des configurations. Si vous modifiez d'autres champs et que vous souhaitez conserver vos configurations actuelles, omettez subscriberConfigs de updateMask.

Requête

PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id?updateMask=endpointUri
{
  "endpointUri": "https://myapp.com/new-webhooks/health"
}

Réponse

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

Supprimer un abonné

Utilisez le delete point de terminaison pour supprimer un abonné de votre projet. Une fois supprimé, l'abonné ne recevra plus de notifications.

Requête

DELETE https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id

Réponse

Un corps de réponse vide avec l'état HTTP `200 OK` est renvoyé si la suppression a réussi.

{}

Validation des points de terminaison

Pour garantir la sécurité et la fiabilité de la diffusion de vos notifications, l'API Google Health effectue une négociation de validation obligatoire en deux étapes chaque fois que vous créez un abonné ou que vous modifiez sa configuration de point de terminaison (endpointUri ou endpointAuthorization). Ce processus est effectué de manière synchrone lors de l'appel d'API. Le service envoie deux requêtes POST automatisées à l'URI de votre point de terminaison, à l'aide du user-agent Google-Health-API-Webhooks-Verifier, avec le corps JSON {"type": "verification"}.

Négociation autorisée : la première requête est envoyée avec l'en-tête Authorization que vous avez configuré. Votre serveur doit répondre avec l'état 200 OK ou 201 Created.
Défi non autorisé : la deuxième requête est envoyée sans identifiants. Votre serveur doit répondre avec l'état 401 Unauthorized ou 403 Forbidden.

Cette négociation confirme que votre point de terminaison est actif et qu'il applique correctement la sécurité. Si l'une des étapes échoue, la requête API échoue avec une erreur FAILED_PRECONDITION. Ce n'est qu'une fois cette négociation réussie que votre abonné est enregistré et activé pour recevoir des notifications de données de santé.

Rotation des clés

Si vous devez faire pivoter les clés pour endpointAuthorization, procédez comme suit :

Configurez votre point de terminaison pour qu'il accepte les anciennes et les nouvelles valeurs endpointAuthorization.
Mettez à jour la configuration de l'abonné avec la nouvelle valeur endpointAuthorization à l'aide d'une requête patch avec ?updateMask=endpointAuthorization.
Configurez votre point de terminaison pour qu'il n'accepte que la nouvelle valeur endpointAuthorization après avoir confirmé que l'étape 2 a réussi.

Abonnements utilisateur

L'API Google Health vous aide à gérer efficacement les abonnements des utilisateurs, ce qui réduit la nécessité d'un enregistrement manuel lors de l'intégration des utilisateurs.

Abonnements automatiques

Nous vous recommandons d'utiliser les abonnements automatiques. Pour activer cette fonctionnalité, définissez subscriptionCreatePolicy sur AUTOMATIC dans subscriberConfigs pour les types de données spécifiques. Les dataTypes que vous spécifiez avec une règle AUTOMATIC sont les mêmes types de données pour lesquels l'API Google Health envoie des notifications, à condition que le consentement de l'utilisateur soit également accordé pour ces types de données.

Lorsqu'un utilisateur autorise l'application à accéder aux champs d'application correspondant aux types de données avec une règle AUTOMATIC, l'API Google Health suit et envoie automatiquement des notifications pour les types de données résultant de l'intersection entre les types de données consenties par l'utilisateur et les types de données de configuration de l'abonné automatique pour cet utilisateur. Les notifications sont ensuite envoyées à votre point de terminaison chaque fois que cet utilisateur génère de nouvelles données pour ces types. Cela fonctionne pour les utilisateurs qui donnent leur consentement avant ou après la création de l'abonné. Les notifications ne sont pas remplies pour les données générées avant la création de l'abonné.

Si un utilisateur révoque son consentement, les notifications pour les types de données correspondants s'arrêtent. Les abonnements automatiques sont gérés par Google et ne peuvent pas être listés ni supprimés individuellement. Ils ne sont supprimés que lorsque l'abonné parent est supprimé.

Abonnements manuels

Si votre abonné est configuré avec une subscription_create_policy MANUELLE pour des types de données spécifiques, vous devez créer et gérer explicitement les abonnements pour chaque utilisateur. Un abonnement associe un utilisateur spécifique au point de terminaison de votre abonné pour un ensemble défini de types de données. Les développeurs peuvent utiliser des API spécifiques pour :

Créer des abonnements (manuels) par healthUserId : crée un nouvel abonnement pour un utilisateur spécifique. Cette méthode nécessite que l'abonné ait une SubscriptionCreatePolicy définie sur MANUAL pour les types de données demandés.
Modifier un abonnement (manuel) : modifie les types de données d'un abonnement utilisateur existant.
Supprimer un abonnement (manuel) : supprime un abonnement utilisateur spécifique. Une fois supprimé, le point de terminaison de votre abonné ne recevra plus de notifications pour cet utilisateur pour les types de données associés.
Répertorier les abonnements (manuels) : répertorie tous les abonnements actifs pour un abonné donné. Vous pouvez filtrer les résultats par utilisateur ou par type de données.

Notifications

Lorsque les données d'un utilisateur changent pour un type de données auquel il est abonné, l'API Google Health envoie une requête HTTPS POST à l'URL du point de terminaison de l'abonné.

Format des notifications

La charge utile de la notification est un objet JSON contenant des informations sur la modification des données. Cela inclut l'ID utilisateur, le type de données et les intervalles de temps, que vous pouvez utiliser pour interroger les données mises à jour.

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

Le champ operation indique le type de modification qui a déclenché la notification :

UPSERT: envoyé pour tout ajout ou modification de données.
DELETE: envoyé lorsqu'un utilisateur supprime des données.

Nous vous recommandons de rendre votre logique de gestion des notifications idempotente, en particulier pour les opérations UPSERT, car les nouvelles tentatives peuvent entraîner l'envoi de notifications en double.

Le champ clientProvidedSubscriptionName est un identifiant unique. Pour les abonnements avec une règle MANUAL, ce champ contient le nom d'abonnement persistant fourni par le développeur et spécifié lors de la création de l'abonnement. Cela fournit un ID stable pour la gestion des abonnements manuels. Pour les abonnements créés avec une règle AUTOMATIC, l'API Google Health génère et attribue automatiquement un identifiant unique (un UUID aléatoire) à ce champ pour chaque notification. L'inclusion de clientProvidedSubscriptionName pour les règles manuelles et automatiques garantit un format de charge utile de notification cohérent pour tous les types d'abonnements.

healthUserId est un identifiant de l'API Google Health pour l'utilisateur dont les données ont été modifiées. Si votre application est compatible avec plusieurs utilisateurs, vous pouvez recevoir des notifications pour tout utilisateur ayant donné son consentement à votre application. Lorsque vous recevez une notification, utilisez healthUserId pour identifier les données de l'utilisateur qui ont été modifiées. Vous pouvez ainsi utiliser ses identifiants OAuth pour interroger ses données.

Pour mapper les identifiants OAuth d'un utilisateur à son healthUserId, utilisez le getIdentity point de terminaison. Appelez ce point de terminaison avec les identifiants d'un utilisateur lors de son intégration pour récupérer son healthUserId et stocker ce mappage. Ce mappage ne change pas au fil du temps. Il peut donc être mis en cache indéfiniment. Pour obtenir un exemple, consultez Obtenir l'ID utilisateur. Cela vous permet de sélectionner les identifiants utilisateur appropriés lorsque vous interrogez des données en fonction du healthUserId dans une notification.

Répondre à une notification

Votre serveur doit répondre immédiatement aux notifications avec un code d'état HTTP 204 No Content. Pour éviter les délais d'attente, traitez la charge utile de la notification de manière asynchrone après avoir envoyé la réponse. Si l'API Google Health reçoit un autre code d'état ou si la requête expire, elle tente d'envoyer la notification ultérieurement.

Exemple 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
    });
});

Validation de la signature

Pour garantir l'authenticité des notifications de webhook, la charge utile JSON brute de chaque notification de webhook sortante est signée avec une clé privée à l'aide de PublicKeySign de Tink , fournissant la signature encodée en base64 dans l'en-tête HTTP GOOGLE-HEALTH-API-SIGNATURE de la requête. Ces clés de signature sont automatiquement renouvelées tous les 30 jours, et l'ensemble de clés publiques officiel correspondant est distribué sous forme de fichier JSON à l'URL permanente https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json.

Comment valider la signature ?

Utiliser Tink (recommandé) : les développeurs peuvent valider la signature à l'aide de la primitive PublicKeyVerify de Tink. Récupérez l'ensemble de clés publiques à partir de l'URL permanente, instanciez la primitive PublicKeyVerify avec l'ensemble de clés et validez l'en-tête GOOGLE-HEALTH-API-SIGNATURE décodé par rapport à la charge utile JSON brute du webhook.

Validation manuelle (sans Tink) : si les développeurs choisissent de ne pas utiliser Tink, ils peuvent valider manuellement la signature en procédant comme suit :

Décode en base64 l'en-tête GOOGLE-HEALTH-API-SIGNATURE pour séparer le préfixe Tink de 5 octets (qui contient un préfixe de version de 1 octet et un keyId de 4 octets) de la signature réelle encodée au format DER.
Récupère l'ensemble de clés JSON à partir de https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json.
Recherche la clé correspondant au keyId analysé et décode en base64 son champ de valeur, qui contient un tampon de protocole EcdsaPublicKey sérialisé.
Extrait les coordonnées x et y big-endian (balises Protobuf 3 et 4) de cette charge utile binaire.
Instancie une clé publique ECDSA P-256 standard dans une bibliothèque de chiffrement intégrée à l'aide des coordonnées x et y extraites.
Valide la charge utile JSON brute du webhook par rapport à la signature DER extraite à l'aide de l'algorithme SHA-256.

État et récupération de l'abonné

Si le point de terminaison de votre abonné devient indisponible ou renvoie un code d'état d'erreur (autre que 204), l'API Google Health stocke les notifications en attente pendant sept jours maximum et tente de les diffuser à nouveau avec un délai exponentiel.

Une fois votre point de terminaison de nouveau en ligne et qu'il répond avec 204, l'API diffuse automatiquement le backlog des messages stockés. Les notifications datant de plus de sept jours sont supprimées et ne peuvent pas être récupérées.

Erreurs fréquentes

Code d'erreur	Message	Description	Recommandation
400 Requête incorrecte	Numéro de projet non valide dans le nom de la ressource	Lors de la suppression ou de la modification d'un abonné à l'aide de l'ID de votre projet Google Cloud dans l'URL de la requête au lieu du numéro de projet. Cela s'applique aux abonnements de webhook à l'aide du point de terminaison `projects.subscribers`.	Utilisez le numéro de votre projet Google Cloud dans l'URL de la requête, et non l'ID du projet.
403 Interdit	L'appelant n'a pas l'autorisation requise	Lors de la création ou de la liste des abonnés à l'aide de l'ID de votre projet Google Cloud dans l'URL de la requête au lieu du numéro de projet. Cela s'applique aux abonnements de webhook à l'aide du point de terminaison `projects.subscribers`.	Utilisez le numéro de votre projet Google Cloud dans l'URL de la requête, et non l'ID du projet.

Liens universels et liens vers une application

Dépannage

Abonnements aux webhooks Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Types de données acceptés

Comptes de service IAM

Configurer un compte de service

Rôles CPE

Gérer vos abonnés

Créer un abonné

Requête

Réponse

Répertorier les abonnés

Requête

Réponse

Modifier un abonné

Requête

Réponse

Supprimer un abonné

Requête

Réponse

Validation des points de terminaison

Rotation des clés

Abonnements utilisateur

Abonnements automatiques

Abonnements manuels

Notifications

Format des notifications

Répondre à une notification

Validation de la signature

Comment valider la signature ?

État et récupération de l'abonné

Erreurs fréquentes

Abonnements aux webhooks