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 verificare la presenza di modifiche, il tuo server riceve una richiesta HTTPS POST (webhook) 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:

  • Passaggi
  • Altitudine
  • Distanza
  • Piani
  • Peso
  • Sonno

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
    • https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
  • Metriche di salute, che copre il tipo di dati relativi al peso:
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
  • Sonno, che copre il tipo di dati relativi al sonno:
    • https://www.googleapis.com/auth/googlehealth.sleep
    • https://www.googleapis.com/auth/googlehealth.sleep.readonly

Gestire gli iscritti

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

L'endpoint dell'iscritto deve utilizzare HTTPS (TLSv1.2+) ed essere accessibile pubblicamente. Durante la creazione e gli aggiornamenti degli iscritti, 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 iscritti non vanno a buon fine e viene generata un'eccezione FailedPreconditionException.

Creare un iscritto

Per registrare un nuovo iscritto per il tuo progetto, utilizza l'endpoint create. Devi fornire:

  • endpointUri: l'URL di destinazione per le notifiche webhook.
  • subscriberConfigs: i tipi di dati per cui vuoi ricevere le notifiche e le norme di abbonamento per ciascuno.
  • endpointAuthorization: il meccanismo di autorizzazione per l'endpoint. Deve contenere un authorization_token che fornisci tu. Il valore di authorization_token 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 authorization_token su Bearer R4nd0m5tr1ng123 per l'autenticazione Bearer o Basic dXNlcjpwYXNzd29yZA== per l'autenticazione di base.
  • subscriberId: un identificatore univoco che fornisci per l'iscritto. 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])).

In subscriberConfigs devi impostare subscriptionCreatePolicy per ogni tipo di dati. Imposta AUTOMATIC per utilizzare gli abbonamenti automatici o MANUAL se intendi gestire tu 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": {
    "authorization_token": "Bearer example-secret-token"
  }
}

Risposta

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

Elencare gli iscritti

Utilizza l'endpoint list per recuperare tutti gli iscritti 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",
      "state": "ACTIVE",
      "subscriberConfigs": [
        {
          "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
          "subscriptionCreatePolicy": "AUTOMATIC"
        },
        {
          "dataTypes": ["sleep"],
          "subscriptionCreatePolicy": "MANUAL"
        }
      ],
      "endpointAuthorization": {
        "authorizationTokenSet": true
      }
    }
  ],
  "nextPageToken": ""
}

Aggiornare un iscritto

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

Per aggiornare i campi, fornisci un parametro di query updateMask e un corpo della richiesta. updateMask deve contenere un elenco di nomi di campi separato da virgole che vuoi aggiornare, utilizzando la notazione a cammello per i nomi dei campi (ad esempio, endpointUri). Il corpo della richiesta deve contenere un oggetto Sottoscrittore 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 presenti in updateMask, questi vengono ignorati.

Se aggiorni endpointUri o endpointAuthorization, viene eseguita la verifica dell'endpoint. Per maggiori dettagli, consulta Verifica dell'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'iscritto 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 attuali, 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",
  "state": "ACTIVE",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ],
  "endpointAuthorization": {
    "authorizationTokenSet": true
  }
}

Verifica dell'endpoint

Per garantire la sicurezza e l'affidabilità della distribuzione delle notifiche, l'API Google Health esegue un handshake di verifica obbligatorio in due passaggi ogni volta che crei un iscritto 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 lo user agent Google-Health-API-Webhooks-Verifier, con il corpo JSON {"type": "verification"}.

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

Questo handshake conferma che l'endpoint è attivo e applica correttamente la sicurezza. Se uno dei passaggi non va a buon fine, la richiesta API non va a buon fine e viene generato un errore FAILED_PRECONDITION. Solo dopo che l'handshake è andato a buon fine, l'iscritto viene salvato e attivato per ricevere le notifiche dei dati sanitari.

Rotazione della 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'iscritto con il nuovo valore endpointAuthorization utilizzando una richiesta patch con ?updateMask=endpointAuthorization.
  3. Configura l'endpoint in modo che accetti solo il nuovo valore endpointAuthorization dopo aver verificato che il passaggio 2 sia andato a buon fine.

Eliminare un iscritto

Utilizza l'endpoint delete per rimuovere un iscritto dal tuo progetto. Una volta eliminato, l'iscritto non riceverà più le 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`. 
{}

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. I dataTypes che specifichi con una norma AUTOMATIC sono gli stessi tipi di dati per cui l'API Google Health invia le notifiche, a condizione che il consenso dell'utente sia concesso anche per questi tipi di dati.

Quando un utente concede il consenso dell'applicazione per gli ambiti che corrispondono ai tipi di dati con una norma AUTOMATIC, l'API Google Health monitora e invia automaticamente le 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 dell'iscritto automatico per quell'utente. Le notifiche vengono quindi inviate all'endpoint ogni volta che l'utente genera nuovi dati per questi tipi. Questa funzionalità è disponibile per gli utenti che concedono il consenso prima o dopo la creazione dell'iscritto. Non viene eseguito il backfill delle notifiche per i dati generati prima della creazione dell'iscritto.

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 viene eliminato l'iscritto principale.

Abbonamenti manuali

Se preferisci gestire manualmente gli abbonamenti per ogni utente, imposta subscriptionCreatePolicy su MANUAL in subscriberConfigs. Con questa norma, gli abbonamenti degli utenti non vengono creati automaticamente. Questa funzionalità verrà utilizzata in futuro quando saranno disponibili le API per la gestione degli abbonamenti manuali. Fino a quando queste API non saranno disponibili, ti consigliamo di utilizzare gli abbonamenti AUTOMATIC.

Notifiche

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

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

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 o quando i dati vengono rimossi a causa di un evento di sistema, ad esempio quando un utente revoca l'autorizzazione o elimina il proprio account.

Ti consigliamo di rendere idempotente la logica di gestione delle notifiche, soprattutto per le operazioni UPSERT, poiché i 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.

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 dell'utente che 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 memorizzare questa mappatura. Questa mappatura non cambia nel tempo, quindi può essere memorizzata 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 immediatamente alle notifiche con un codice di stato HTTP 204 No Content. 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 va in timeout, ritenta di inviare la notifica in un secondo momento.

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

Stato e recupero dell'iscritto

Se l'endpoint dell'iscritto non è 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 un backoff esponenziale.

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

Indietro
Link universali e di app
Avanti
Risoluzione dei problemi