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) dès que des données sont disponibles dans l'API Google Health.

Types de données acceptés

Les notifications de webhook sont acceptées pour les types de données suivants :

  • Étapes
  • Altitude
  • Distance
  • Étages
  • Poids
  • Sommeil

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
    • https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
  • Indicateurs de santé, qui couvre le type de données "Poids" :
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
  • Sommeil, qui couvre le type de données "Sommeil" :
    • https://www.googleapis.com/auth/googlehealth.sleep
    • https://www.googleapis.com/auth/googlehealth.sleep.readonly

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 une question 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 point de terminaison create. Vous devez fournir les éléments suivants :

  • 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 authorization_token que vous fournissez. La valeur de authorization_token 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 authorization_token sur Bearer R4nd0m5tr1ng123 pour l'authentification Bearer ou sur Basic dXNlcjpwYXNzd29yZA== pour l'authentification de base.
  • 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])).

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": {
    "authorization_token": "Bearer example-secret-token"
  }
}

Réponse

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

Répertorier les abonnés

Utilisez le point de terminaison list 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",
      "state": "ACTIVE",
      "subscriberConfigs": [
        {
          "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
          "subscriptionCreatePolicy": "AUTOMATIC"
        },
        {
          "dataTypes": ["sleep"],
          "subscriptionCreatePolicy": "MANUAL"
        }
      ],
      "endpointAuthorization": {
        "authorizationTokenSet": true
      }
    }
  ],
  "nextPageToken": ""
}

Modifier un abonné

Utilisez le point de terminaison patch 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 du point 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",
  "state": "ACTIVE",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ],
  "endpointAuthorization": {
    "authorizationTokenSet": true
  }
}

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 la configuration de son 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 un état 200 OK ou 201 Created.
  • Question non autorisée : la deuxième requête est envoyée sans identifiants. Votre serveur doit répondre avec un é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 :

  1. Configurez votre point de terminaison pour qu'il accepte les anciennes et les nouvelles valeurs endpointAuthorization.
  2. Mettez à jour la configuration de l'abonné avec la nouvelle valeur endpointAuthorization à l'aide d'une requête patch avec ?updateMask=endpointAuthorization.
  3. 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.

Supprimer un abonné

Utilisez le point de terminaison delete 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. 
{}

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 que ceux pour lesquels l'API Google Health envoie des notifications, à condition que l'utilisateur ait également donné son consentement pour ces types de données.

Lorsqu'un utilisateur autorise l'application à accéder aux champs d'application correspondant à des 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 pour lesquels l'utilisateur a donné son consentement 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 vous préférez gérer manuellement les abonnements de chaque utilisateur, définissez subscriptionCreatePolicy sur MANUAL dans subscriberConfigs. Avec cette règle, les abonnements utilisateur ne sont pas créés automatiquement. Cette fonctionnalité sera utilisée à l'avenir lorsque des API de gestion des abonnements manuels seront disponibles. En attendant, nous vous recommandons d'utiliser les abonnements AUTOMATIC.

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

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 ou lorsque des données sont supprimées en raison d'un événement système, par exemple lorsqu'un utilisateur révoque une autorisation ou supprime son compte.

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 autorisé 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 point de terminaison getIdentity. 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
    });
});

É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.

Précédent
Liens universels et liens vers une application
Suivant
Dépannage