Abbonamenti webhook

L'API Google Health consente alla tua applicazione di ricevere notifiche in tempo reale quando i dati sanitari di un utente cambiano. Anziché eseguire il polling per rilevare le modifiche, il server riceve una richiesta POST HTTPS (webhook){:target="_blank" class="external"} non appena i dati sono disponibili nell'API Google Health.

Tipi di dati supportati

Le notifiche webhook sono supportate per i seguenti tipi di dati:

  • Minuti in zona attiva
  • Livello di attività
  • Altitudine
  • Glicemia
  • Grasso corporeo
  • Calorie nella zona del battito cardiaco
  • Variabilità del battito cardiaco giornaliera
  • Zone battito cardiaco giornaliero
  • Saturazione di ossigeno giornaliera
  • Frequenza respiratoria giornaliera
  • Battito cardiaco a riposo giornaliero
  • Derivazioni della temperatura del sonno giornaliera
  • Distanza
  • Esercizio
  • Piani
  • Frequenza cardiaca
  • Variabilità del battito cardiaco
  • Altezza
  • Diario dell'idratazione
  • Diario alimentare
  • Riepilogo del sonno della frequenza respiratoria
  • VO2 max corsa
  • Periodo di sedentarietà
  • Sonno
  • Passaggi
  • Tempo nella zona del battito cardiaco
  • Calorie totali
  • Peso

Le notifiche vengono inviate per questi tipi di dati solo quando un utente ha concesso il consenso per uno degli ambiti corrispondenti:

  • Attività, che copre i tipi di dati relativi a passi, altitudine, distanza e piani:
    • https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
    • https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
  • Metriche di salute, che copre il tipo di dati sul peso:
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.writeonly
  • Sonno, che copre il tipo di dati sul sonno:
    • https://www.googleapis.com/auth/googlehealth.sleep.readonly
    • https://www.googleapis.com/auth/googlehealth.sleep.writeonly

Service account IAM

Sebbene non sia obbligatorio, ti consigliamo di utilizzare un service account IAM quando configuri i sottoscrittori per l'API Google Health. I service account offrono una maggiore sicurezza per i carichi di lavoro delle applicazioni rispetto agli account utente standard grazie alle seguenti funzionalità:

  • Credenziali automatiche di breve durata:quando vengono associate a un ambiente di esecuzione Google Cloud (come Compute Engine, Cloud Run o Google Kubernetes Engine), gli account di servizio ottengono e ruotano automaticamente credenziali sicure e di breve durata. In questo modo vengono eliminati i rischi di gestione e archiviazione di chiavi statiche persistenti.
  • Principio del privilegio minimo: i service account forniscono identità dedicate per i workload. Puoi concedere solo le autorizzazioni specifiche necessarie per gestire gli endpoint dei sottoscrittori, evitando un accesso più ampio alle tue risorse Google Cloud.
  • Indipendenza del ciclo di vita: i service account funzionano indipendentemente dall'account di qualsiasi singolo utente, garantendo che i cambiamenti di personale non influiscano sulla stabilità dell'autenticazione a lungo termine.

Configura un service account

Per configurare l'applicazione abbonato in modo che esegua l'autenticazione utilizzando un service account:

  1. Crea un service account:nella console Google Cloud, vai alla pagina IAM e amministrazione del tuo progetto per creare un nuovo service account gestito dall'utente.
  2. Concedi i ruoli IAM necessari: assegna all'account di servizio i ruoli appropriati necessari per gestire gli abbonati nel tuo progetto Google Cloud.
  3. Collega il service account al tuo workload:configura l'ambiente che ospita la logica del tuo abbonato in modo che venga eseguito come nuovo service account. In questo modo, il codice dell'applicazione (ad esempio le librerie client delle API di Google) può rilevare e utilizzare automaticamente le credenziali temporanee del service account quando chiama l'API REST projects.subscribers.

Ruoli CPE

Per gestire gli abbonati o gli abbonamenti all'API Google Health, devi concedere il ruolo appropriato al service account rappresentato che effettua le chiamate API. A seconda del livello di accesso necessario, assegna uno dei seguenti ruoli:

  • Google Health API Read
  • Google Health API Editor
  • Google Health API Admin

Scopri di più sui ruoli e le autorizzazioni IAM dell'API Google Health.

Gestire gli iscritti

Prima di poter ricevere le notifiche, devi registrare un sottoscrittore, che rappresenta l'endpoint di notifica della tua applicazione. Puoi gestire gli iscritti utilizzando l'API REST disponibile all'indirizzo projects.subscribers.

L'endpoint del sottoscrittore deve utilizzare HTTPS (TLSv1.2+) ed essere accessibile pubblicamente. Durante la creazione e gli aggiornamenti degli abbonati, l'API Google Health esegue una verifica per assicurarsi che tu sia il proprietario dell'URI dell'endpoint. Se la verifica non va a buon fine, le operazioni di creazione e aggiornamento degli abbonati non vengono completate con un FailedPreconditionException.

Crea un abbonato

Per registrare un nuovo abbonato al tuo progetto, utilizza l'endpoint create. Devi fornire:

  • project-id: il numero del progetto in cui è stato creato il service account webhook.
  • subscriberId: un identificatore univoco fornito per l'abbonato. Questo ID deve essere compreso tra 4 e 36 caratteri e corrispondere all'espressione regolare ([a-z]([a-z0-9-]{2,34}[a-z0-9])).
  • endpointUri: l'URL di destinazione per le notifiche webhook.
  • subscriberConfigs: i tipi di dati per cui vuoi ricevere notifiche e la policy di abbonamento per ciascuno.
  • endpointAuthorization: il meccanismo di autorizzazione per l'endpoint. Deve contenere un secret che fornisci. Il valore di secret viene inviato nell'intestazione Authorization con ogni messaggio di notifica. Puoi utilizzare questo token per verificare che le richieste in entrata provengano dall'API Google Health. Ad esempio, puoi impostare secret su Bearer R4nd0m5tr1ng123 per l'autenticazione di connessione (bearer) o Basic dXNlcjpwYXNzd29yZA== per l'autenticazione di base.

In subscriberConfigs devi impostare subscriptionCreatePolicy per ogni tipo di dati. Impostalo su AUTOMATIC per utilizzare gli abbonamenti automatici o su MANUAL se intendi gestire personalmente gli abbonamenti degli utenti. Per ulteriori dettagli su ogni opzione, consulta Abbonamenti automatici e Abbonamenti manuali.

Richiesta

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

Risposta

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

Elenco degli iscritti

Utilizza l'endpoint list per recuperare tutti gli abbonati registrati per il tuo progetto.

Richiesta

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

Risposta

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

Aggiornare un abbonato

Utilizza l'endpoint patch per aggiornare un abbonato nel tuo progetto. I campi che possono essere aggiornati sono endpointUri, subscriberConfigs e endpointAuthorization.

Aggiorni i campi fornendo un parametro di query updateMask e un corpo della richiesta. updateMask deve contenere un elenco separato da virgole dei nomi dei campi che vuoi aggiornare, utilizzando la notazione camel case per i nomi dei campi (ad esempio, endpointUri). Il corpo della richiesta deve contenere un oggetto Subscriber parziale con i nuovi valori per i campi che vuoi aggiornare. Vengono aggiornati solo i campi specificati in updateMask. Se fornisci campi nel corpo della richiesta che non sono in updateMask, questi vengono ignorati.

Se aggiorni endpointUri o endpointAuthorization, viene eseguita la verifica degli endpoint. Per maggiori dettagli, vedi Verifica degli endpoint.

Quando aggiorni subscriberConfigs, tieni presente che si tratta di una sostituzione completa, non di un'unione. Se subscriberConfigs è incluso in updateMask, tutte le configurazioni memorizzate per l'abbonato vengono sovrascritte con l'elenco fornito nel corpo della richiesta. Per aggiungere o rimuovere una configurazione, devi fornire l'insieme completo di configurazioni. Se stai aggiornando altri campi e vuoi mantenere le configurazioni correnti, ometti subscriberConfigs da updateMask.

Richiesta

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

Risposta

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

Eliminare un abbonato

Utilizza l'endpoint delete per rimuovere un abbonato dal tuo progetto. Una volta eliminato, l'iscritto non riceverà più notifiche.

Richiesta

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

Risposta

Se l'eliminazione va a buon fine, viene restituito un corpo della risposta vuoto con lo stato HTTP "200 OK". 
{}

Verifica endpoint

Per garantire la sicurezza e l'affidabilità della distribuzione delle notifiche, l'API Google Health esegue un handshake di verifica in due passaggi obbligatorio ogni volta che crei un abbonato o aggiorni la configurazione dell'endpoint (endpointUri o endpointAuthorization). Questa procedura viene eseguita in modo sincrono durante la chiamata API. Il servizio invia due richieste POST automatiche all'URI dell'endpoint, utilizzando User-Agent Google-Health-API-Webhooks-Verifier, con il corpo JSON {"type": "verification"}.

  • Handshake autorizzato: la prima richiesta viene inviata con l'intestazione Authorization configurata. Il server deve rispondere con uno stato 200 OK o 201 Created.
  • Sfida non autorizzata: la seconda richiesta viene inviata senza credenziali. Il server deve rispondere con uno stato 401 Unauthorized o 403 Forbidden.

Questo handshake conferma che l'endpoint è attivo e applica correttamente la sicurezza. Se uno dei due passaggi non va a buon fine, la richiesta API non va a buon fine e viene visualizzato un errore FAILED_PRECONDITION. Solo dopo che questo handshake ha esito positivo, il tuo abbonato viene salvato e attivato per ricevere le notifiche dei dati sanitari.

Rotazione chiave

Se devi ruotare le chiavi per endpointAuthorization, segui questi passaggi:

  1. Configura l'endpoint in modo che accetti sia i valori endpointAuthorization vecchi che quelli nuovi.
  2. Aggiorna la configurazione dell'abbonato con il nuovo valore endpointAuthorization utilizzando una richiesta patch con ?updateMask=endpointAuthorization.
  3. Configura l'endpoint in modo che accetti solo il nuovo valore di endpointAuthorization dopo aver verificato che il passaggio 2 sia andato a buon fine.

Abbonamenti utente

L'API Google Health ti aiuta a gestire in modo efficiente gli abbonamenti degli utenti, riducendo la necessità di registrazione manuale durante l'onboarding degli utenti.

Abbonamenti automatici

Ti consigliamo di utilizzare gli abbonamenti automatici. Per attivare questa funzionalità, imposta subscriptionCreatePolicy su AUTOMATIC in subscriberConfigs per i tipi di dati specifici. Il dataTypes che specifichi con un criterio AUTOMATIC sono gli stessi tipi di dati per i quali l'API Google Health invia notifiche, a condizione che venga concesso anche il consenso dell'utente per questi tipi di dati.

Quando un utente concede il consenso all'applicazione per gli ambiti che corrispondono a tipi di dati con un criterio AUTOMATIC, l'API Google Health monitora e invia automaticamente notifiche per i tipi di dati risultanti dall'intersezione tra i tipi di dati per i quali è stato dato il consenso dall'utente e i tipi di dati di configurazione automatica dell'abbonato per quell'utente. Le notifiche vengono quindi inviate al tuo endpoint ogni volta che l'utente genera nuovi dati per questi tipi. Funziona per gli utenti che concedono il consenso prima o dopo la creazione dell'abbonato. Le notifiche non vengono compilate per i dati generati prima della creazione dell'abbonato.

Se un utente revoca il consenso, le notifiche per i tipi di dati corrispondenti verranno interrotte. Gli abbonamenti automatici sono gestiti da Google e non possono essere elencati o eliminati singolarmente; vengono rimossi solo quando l'abbonato principale viene eliminato.

Abbonamenti manuali

Se il tuo abbonato è configurato con un subscription_create_policy MANUALE per tipi di dati specifici, devi creare e gestire esplicitamente gli abbonamenti per ogni utente. Un abbonamento collega un utente specifico all'endpoint dell'abbonato per un insieme definito di tipi di dati. Gli sviluppatori possono utilizzare API specifiche per:

  • Crea sottoscrizioni (manuali) per healthUserId: crea una nuova sottoscrizione per un utente specifico. Questo metodo richiede che l'abbonato abbia un SubscriptionCreatePolicy impostato su MANUAL per i tipi di dati richiesti.
  • Aggiorna (manuale) abbonamento: aggiorna i tipi di dati per un abbonamento utente esistente.
  • Elimina abbonamento (manuale) - Elimina l'abbonamento di un utente specifico. Una volta eliminato, l'endpoint del sottoscrittore non riceverà più notifiche per questo utente per i tipi di dati associati.
  • Elenco delle iscrizioni (manuali): elenca tutte le iscrizioni attive per un determinato abbonato. Puoi filtrare i risultati per utente o tipo di dati.

Notifiche

Quando i dati di un utente cambiano per un tipo di dati a cui è stato effettuato l'abbonamento, l'API Google Health invia una richiesta POST HTTPS all'URL dell'endpoint del sottoscrittore.

Formato delle notifiche

Il payload della notifica è un oggetto JSON contenente i dettagli della modifica dei dati. Sono inclusi l'ID utente, il tipo di dati e gli intervalli di tempo, che puoi utilizzare per eseguire query sui dati aggiornati.

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

Il campo operation indica il tipo di modifica che ha attivato la notifica:

  • UPSERT: inviato per qualsiasi aggiunta o modifica dei dati.
  • DELETE: inviato quando un utente elimina i dati.

Ti consigliamo di rendere idempotente la logica di gestione delle notifiche, in particolare per le operazioni UPSERT, poiché i nuovi tentativi possono causare l'invio di notifiche duplicate.

Il campo clientProvidedSubscriptionName è un identificatore univoco. Per gli abbonamenti con una norma MANUAL, questo campo contiene il nome dell'abbonamento persistente fornito dallo sviluppatore specificato al momento della creazione dell'abbonamento. In questo modo, viene fornito un ID stabile per la gestione degli abbonamenti manuali. Per gli abbonamenti creati con una norma AUTOMATIC, l'API Google Health genera e assegna automaticamente un identificatore univoco (un UUID casuale) a questo campo per ogni notifica. L'inclusione di clientProvidedSubscriptionName per le norme manuali e automatiche garantisce un formato del payload di notifica coerente per tutti i tipi di abbonamento.

L'healthUserId è un identificatore dell'API Google Health per l'utente i cui dati sono stati modificati. Se la tua applicazione supporta più utenti, potresti ricevere notifiche per qualsiasi utente che ha concesso il consenso alla tua applicazione. Quando ricevi una notifica, utilizza healthUserId per identificare i dati di quale utente sono stati modificati, in modo da poter utilizzare le sue credenziali OAuth per eseguire query sui dati.

Per mappare le credenziali OAuth di un utente al suo healthUserId, utilizza l'endpoint getIdentity. Chiama questo endpoint con le credenziali di un utente durante l'onboarding dell'utente per recuperare il suo healthUserId e memorizza questa mappatura. Questo mapping non cambia nel tempo, quindi può essere memorizzato nella cache a tempo indeterminato. Per un esempio, vedi Recuperare l'ID utente. In questo modo puoi selezionare le credenziali utente corrette quando esegui query sui dati in base a healthUserId in una notifica.

Rispondere a una notifica

Il server deve rispondere alle notifiche con un codice di stato HTTP 204 No Content immediatamente. Per evitare timeout, elabora il payload della notifica in modo asincrono dopo aver inviato la risposta. Se l'API Google Health riceve un altro codice di stato o la richiesta scade con timeout, riprova a inviare la notifica in un secondo momento.

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

Verifica della firma

Per garantire l'autenticità delle notifiche webhook, il payload JSON non elaborato di ogni notifica webhook in uscita viene firmato con una chiave privata utilizzando PublicKeySign di Tink, fornendo la firma codificata in Base64 nell'intestazione HTTP GOOGLE-HEALTH-API-SIGNATURE nella richiesta. Queste chiavi di firma vengono ruotate automaticamente ogni 30 giorni e il set di chiavi pubbliche ufficiali corrispondente viene distribuito come file JSON all'URL permanente https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json.

Come verificare la firma

Utilizzo di Tink (consigliato): gli sviluppatori possono verificare la firma utilizzando la primitiva PublicKeyVerify di Tink. Recupera il keyset pubblico dall'URL permanente, crea un'istanza della primitiva PublicKeyVerify con il keyset e verifica l'intestazione GOOGLE-HEALTH-API-SIGNATURE decodificata rispetto al payload JSON webhook non elaborato.

Verifica manuale (senza Tink): se gli sviluppatori scelgono di non utilizzare Tink, possono verificare manualmente la firma seguendo questi passaggi:

  1. Decodifica in base64 l'intestazione GOOGLE-HEALTH-API-SIGNATURE per separare il prefisso Tink di 5 byte (che contiene un prefisso di versione di 1 byte e un keyId di 4 byte) dalla firma effettiva con codifica DER.
  2. Recupera il keyset JSON da https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json.
  3. Individua la chiave corrispondente a keyId analizzato e decodifica in Base64 il relativo campo valore, che contiene un buffer di protocollo EcdsaPublicKey serializzato.
  4. Estrai le coordinate x e y big-endian (tag Protobuf 3 e 4) da questo payload binario.
  5. Crea un'istanza di una chiave pubblica ECDSA P-256 standard in una libreria di crittografia integrata utilizzando le coordinate x e y estratte.
  6. Verifica il payload JSON webhook non elaborato rispetto alla firma DER estratta utilizzando l'algoritmo SHA-256.

Stato dell'iscritto e recupero

Se l'endpoint del tuo abbonato non è più disponibile o restituisce un codice di stato di errore (diverso da 204), l'API Google Health memorizza le notifiche in attesa per un massimo di 7 giorni e ritenta la consegna con backoff esponenziale.

Una volta che l'endpoint è di nuovo online e risponde con 204, l'API fornisce automaticamente l'arretrato dei messaggi archiviati. Le notifiche più vecchie di 7 giorni vengono eliminate e non possono essere recuperate.

Errori comuni

Codice di errore Messaggio Descrizione Suggerimento
400 Richiesta errata Numero di progetto non valido nel nome della risorsa Quando elimini o aggiorni un sottoscrittore utilizzando l'ID progetto Google Cloud nell'URL della richiesta anziché il numero di progetto. Ciò vale per gli abbonamenti webhook che utilizzano l'endpoint projects.subscribers. Utilizza il numero del tuo progetto Google Cloud nell'URL della richiesta, non l'ID progetto.
403 Forbidden Il chiamante non dispone dell'autorizzazione Quando crei o elenchi i sottoscrittori utilizzando l'ID progetto Google Cloud nell'URL della richiesta anziché il numero di progetto. Ciò vale per gli abbonamenti webhook che utilizzano l'endpoint projects.subscribers. Utilizza il numero del tuo progetto Google Cloud nell'URL della richiesta, non l'ID progetto.

Indietro
Link universali e di app
Avanti
Risoluzione dei problemi