Webhook-Abos


Mit der Google Health API kann Ihre Anwendung Echtzeitbenachrichtigungen erhalten, wenn sich die Gesundheitsdaten eines Nutzers ändern. Anstatt nach Änderungen zu suchen, empfängt Ihr Server eine HTTPS-POST-Anfrage (Webhook), sobald Daten in der Google Health API verfügbar sind.

Unterstützte Datentypen

Webhook-Benachrichtigungen werden für die folgenden Datentypen unterstützt:

  • Schritte
  • Höhe
  • Entfernung
  • Stockwerke
  • Gewicht
  • Schlaf

Benachrichtigungen werden für diese Datentypen nur gesendet, wenn ein Nutzer die Einwilligung für einen der entsprechenden Bereiche erteilt hat:

  • Aktivität, die die Datentypen „Schritte“, „Höhe“, „Distanz“ und „Etagen“ umfasst:
    • https://www.googleapis.com/auth/googlehealth.activity_and_fitness
    • https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
  • Gesundheitsmesswerte, einschließlich des Datentyps „Gewicht“:
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
  • Schlaf, der den Schlafdatentyp umfasst:
    • https://www.googleapis.com/auth/googlehealth.sleep
    • https://www.googleapis.com/auth/googlehealth.sleep.readonly

Abonnenten verwalten

Bevor Sie Benachrichtigungen erhalten können, müssen Sie einen Subscriber registrieren, der den Benachrichtigungsendpunkt Ihrer Anwendung darstellt. Du kannst Abonnenten über die REST API unter projects.subscribers verwalten.

Ihr Abonnentenendpunkt muss HTTPS (TLSv1.2+) verwenden und öffentlich zugänglich sein. Beim Erstellen und Aktualisieren von Abonnenten führt die Google Health API eine Bestätigungsanfrage durch, um sicherzustellen, dass Sie der Inhaber des Endpunkt-URI sind. Wenn die Bestätigung fehlschlägt, schlagen Vorgänge zum Erstellen und Aktualisieren von Abonnenten mit einem FailedPreconditionException fehl.

Abonnenten erstellen

Verwenden Sie den Endpunkt create, um einen neuen Abonnenten für Ihr Projekt zu registrieren. Sie müssen Folgendes angeben:

  • endpointUri: Die Ziel-URL für Webhook-Benachrichtigungen.
  • subscriberConfigs: Die Datentypen, für die Sie Benachrichtigungen erhalten möchten, und die Abo-Richtlinie für jeden Typ.
  • endpointAuthorization: Der Autorisierungsmechanismus für Ihren Endpunkt. Es muss ein authorization_token enthalten, das Sie bereitstellen. Der Wert von authorization_token wird mit jeder Benachrichtigungsnachricht im Header Authorization gesendet. Mit diesem Token können Sie überprüfen, ob eingehende Anfragen von der Google Health API stammen. Sie können beispielsweise authorization_token für die Bearer-Authentifizierung auf Bearer R4nd0m5tr1ng123 oder für die Basisauthentifizierung auf Basic dXNlcjpwYXNzd29yZA== festlegen.
  • subscriberId: Eine eindeutige Kennung, die Sie für den Abonnenten angeben. Diese ID muss zwischen 4 und 36 Zeichen lang sein und dem regulären Ausdruck ([a-z]([a-z0-9-]{2,34}[a-z0-9])) entsprechen.

In subscriberConfigs müssen Sie subscriptionCreatePolicy für jeden Datentyp festlegen. Legen Sie AUTOMATIC fest, um automatische Abos zu verwenden, oder MANUAL, wenn Sie Nutzerabos selbst verwalten möchten. Weitere Informationen zu den einzelnen Optionen finden Sie unter Automatische Abos und Manuelle Abos.

Anfrage

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

Antwort

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

Abonnenten auflisten

Mit dem Endpunkt list können Sie alle Abonnenten abrufen, die für Ihr Projekt registriert sind.

Anfrage

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

Antwort

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

Abonnenten aktualisieren

Verwenden Sie den patch-Endpunkt, um einen Abonnenten in Ihrem Projekt zu aktualisieren. Folgende Felder können aktualisiert werden: endpointUri, subscriberConfigs und endpointAuthorization.

Sie aktualisieren Felder, indem Sie einen updateMask-Abfrageparameter und einen Anfragetext angeben. updateMask muss eine durch Kommas getrennte Liste von Feldnamen enthalten, die Sie aktualisieren möchten. Verwenden Sie für Feldnamen die Kamel-Schreibweise (z. B. endpointUri). Der Anfragetext muss ein partielles Subscriber-Objekt mit den neuen Werten für die Felder enthalten, die Sie aktualisieren möchten. Nur die in updateMask angegebenen Felder werden aktualisiert. Wenn Sie im Anfragetext Felder angeben, die nicht in updateMask enthalten sind, werden sie ignoriert.

Wenn Sie endpointUri oder endpointAuthorization aktualisieren, wird die Endpunktprüfung durchgeführt. Weitere Informationen finden Sie unter Endpunktprüfung.

Beachten Sie beim Aktualisieren von subscriberConfigs, dass es sich um einen vollständigen Ersatz und nicht um eine Zusammenführung handelt. Wenn subscriberConfigs in updateMask enthalten ist, werden alle gespeicherten Konfigurationen für diesen Abonnenten mit der im Anfragetext angegebenen Liste überschrieben. Wenn Sie eine Konfiguration hinzufügen oder entfernen möchten, müssen Sie den vollständigen Satz von Konfigurationen angeben. Wenn Sie andere Felder aktualisieren und Ihre aktuellen Konfigurationen beibehalten möchten, lassen Sie subscriberConfigs in updateMask weg.

Anfrage

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

Antwort

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

Endpunktprüfung

Um die Sicherheit und Zuverlässigkeit der Benachrichtigungsübermittlung zu gewährleisten, führt die Google Health API bei jedem Erstellen eines Abonnenten oder Aktualisieren seiner Endpunktkonfiguration (endpointUri oder endpointAuthorization) einen obligatorischen zweistufigen Bestätigungshandshake durch. Dieser Prozess wird synchron während des API-Aufrufs ausgeführt. Der Dienst sendet zwei automatisierte POST-Anfragen an Ihren Endpunkt-URI mit dem User-Agent Google-Health-API-Webhooks-Verifier und dem JSON-Text {"type": "verification"}.

  • Autorisierter Handshake: Die erste Anfrage wird mit dem konfigurierten Authorization-Header gesendet. Ihr Server muss mit dem Status 200 OK oder 201 Created antworten.
  • Nicht autorisierte Challenge: Die zweite Anfrage wird ohne Anmeldedaten gesendet. Ihr Server muss mit dem Status 401 Unauthorized oder 403 Forbidden antworten.

Durch diesen Handshake wird bestätigt, dass Ihr Endpunkt aktiv ist und die Sicherheit korrekt durchsetzt. Wenn einer der beiden Schritte fehlschlägt, schlägt die API-Anfrage mit dem Fehler FAILED_PRECONDITION fehl. Erst nach erfolgreichem Abschluss dieses Handshake wird dein Abonnent gespeichert und aktiviert, um Benachrichtigungen zu Gesundheitsdaten zu erhalten.

Schlüsselrotation

Wenn Sie Schlüssel für endpointAuthorization rotieren müssen, gehen Sie so vor:

  1. Konfigurieren Sie Ihren Endpunkt so, dass er sowohl alte als auch neue endpointAuthorization-Werte akzeptiert.
  2. Aktualisieren Sie die Abonnentenkonfiguration mit dem neuen endpointAuthorization-Wert über eine patch-Anfrage mit ?updateMask=endpointAuthorization.
  3. Konfigurieren Sie Ihren Endpunkt so, dass er nur den neuen Wert endpointAuthorization akzeptiert, nachdem Sie bestätigt haben, dass Schritt 2 erfolgreich war.

Abonnenten löschen

Verwenden Sie den Endpunkt delete, um einen Abonnenten aus Ihrem Projekt zu entfernen. Nach dem Löschen erhält der Abonnent keine Benachrichtigungen mehr.

Anfrage

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

Antwort

Wenn das Löschen erfolgreich ist, wird ein leerer Antworttext mit dem HTTP-Status „200 OK“ zurückgegeben. 
{}

Nutzerabos

Mit der Google Health API können Sie Nutzerabos effizient verwalten und die manuelle Registrierung bei der Nutzerregistrierung reduzieren.

Automatische Abos

Wir empfehlen die Verwendung automatischer Abos. Wenn Sie diese Funktion aktivieren möchten, legen Sie subscriptionCreatePolicy in Ihrem subscriberConfigs für die jeweiligen Datentypen auf AUTOMATIC fest. Die dataTypes, die Sie mit einer AUTOMATIC-Richtlinie angeben, sind dieselben Datentypen, für die die Google Health API Benachrichtigungen sendet, sofern die Einwilligung des Nutzers auch für diese Datentypen erteilt wurde.

Wenn ein Nutzer die Einwilligung für Bereiche erteilt, die Datentypen mit einer AUTOMATIC-Richtlinie entsprechen, werden die Datentypen, die sich aus der Überschneidung zwischen den vom Nutzer genehmigten Datentypen und den Datentypen der automatischen Abonnentenkonfiguration für diesen Nutzer ergeben, automatisch von der Google Health API erfasst und es werden Benachrichtigungen für sie gesendet. Benachrichtigungen werden dann an Ihren Endpunkt gesendet, wenn dieser Nutzer neue Daten für diese Typen generiert. Das funktioniert für Nutzer, die die Einwilligung entweder vor oder nach der Erstellung des Abonnenten erteilen. Benachrichtigungen werden nicht für Daten per Backfill ausgefüllt, die vor der Erstellung des Abonnenten generiert wurden.

Wenn ein Nutzer die Einwilligung widerruft, werden keine Benachrichtigungen mehr für die entsprechenden Datentypen gesendet. Automatische Abos werden von Google verwaltet und können nicht einzeln aufgeführt oder gelöscht werden. Sie werden nur entfernt, wenn der übergeordnete Abonnent gelöscht wird.

Manuelle Abos

Wenn Sie Abos für jeden Nutzer lieber manuell verwalten möchten, legen Sie in subscriberConfigs subscriptionCreatePolicy auf MANUAL fest. Gemäß dieser Richtlinie werden Nutzerabos nicht automatisch erstellt. Diese Funktion wird in Zukunft verwendet, wenn APIs zur Verwaltung manueller Abos verfügbar sind. Bis diese APIs verfügbar sind, empfehlen wir die Verwendung von AUTOMATIC-Abos.

Benachrichtigungen

Wenn sich die Daten eines Nutzers für einen abonnierten Datentyp ändern, sendet die Google Health API eine HTTPS-POST-Anfrage an die Subscriber-Endpunkt-URL.

Benachrichtigungsformat

Die Benachrichtigungs-Payload ist ein JSON-Objekt mit Details zur Datenänderung. Dazu gehören die Nutzer-ID, der Datentyp und die Zeitintervalle, mit denen Sie die aktualisierten Daten abfragen können.

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

Das Feld operation gibt den Typ der Änderung an, die die Benachrichtigung ausgelöst hat:

  • UPSERT: Wird bei jeder Datenänderung oder jedem Hinzufügen von Daten gesendet.
  • DELETE: Wird gesendet, wenn ein Nutzer Daten löscht oder wenn Daten aufgrund eines Systemereignisses entfernt werden, z. B. wenn ein Nutzer die Berechtigung widerruft oder sein Konto löscht.

Wir empfehlen, die Logik für die Benachrichtigungsbearbeitung idempotent zu gestalten, insbesondere für UPSERT-Vorgänge, da bei Wiederholungen doppelte Benachrichtigungen gesendet werden können.

Das Feld clientProvidedSubscriptionName ist eine eindeutige Kennung. Bei Abos mit einer MANUAL-Richtlinie enthält dieses Feld den vom Entwickler angegebenen dauerhaften Abonamen, der beim Erstellen des Abos angegeben wurde. Damit erhalten Sie eine stabile ID zum Verwalten manueller Abos. Für Abos, die mit einer AUTOMATIC-Richtlinie erstellt wurden, generiert und weist die Google Health API automatisch eine eindeutige Kennung (eine zufällige UUID) für dieses Feld für jede Benachrichtigung zu. Wenn Sie clientProvidedSubscriptionName sowohl für manuelle als auch für automatische Richtlinien einfügen, wird ein einheitliches Benachrichtigungs-Nutzlastformat für alle Abotypen gewährleistet.

Die healthUserId ist eine Google Health API-Kennung für den Nutzer, dessen Daten sich geändert haben. Wenn Ihre Anwendung mehrere Nutzer unterstützt, können Sie Benachrichtigungen für jeden Nutzer erhalten, der Ihrer Anwendung die Einwilligung erteilt hat. Wenn Sie eine Benachrichtigung erhalten, verwenden Sie healthUserId, um herauszufinden, welche Nutzerdaten sich geändert haben. So können Sie die OAuth-Anmeldedaten des Nutzers verwenden, um seine Daten abzufragen.

Wenn Sie die OAuth-Anmeldedaten eines Nutzers seinem healthUserId zuordnen möchten, verwenden Sie den Endpunkt getIdentity. Rufen Sie diesen Endpunkt während des Onboardings von Nutzern mit den Anmeldedaten eines Nutzers auf, um seine healthUserId abzurufen und diese Zuordnung zu speichern. Diese Zuordnung ändert sich nicht im Laufe der Zeit und kann daher unbegrenzt im Cache gespeichert werden. Ein Beispiel finden Sie unter Nutzer-ID abrufen. So können Sie die richtigen Nutzeranmeldedaten auswählen, wenn Sie Daten basierend auf dem healthUserId in einer Benachrichtigung abfragen.

Reagieren auf eine Benachrichtigung

Ihr Server muss sofort mit dem HTTP-Statuscode 204 No Content auf Benachrichtigungen antworten. Um Zeitüberschreitungen zu vermeiden, verarbeiten Sie die Benachrichtigungsnutzlast asynchron, nachdem Sie die Antwort gesendet haben. Wenn die Google Health API einen anderen Statuscode empfängt oder bei der Anfrage eine Zeitüberschreitung auftritt, wird die Benachrichtigung später noch einmal gesendet.

Node.js-Beispiel (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
    });
});

Abonnentenstatus und Wiederherstellung

Wenn dein Abonnentenendpunkt nicht mehr verfügbar ist oder einen Fehlerstatuscode (alles außer 204) zurückgibt, speichert die Google Health API ausstehende Benachrichtigungen bis zu 7 Tage lang und versucht es mit exponentiellem Backoff noch einmal.

Sobald Ihr Endpunkt wieder online ist und mit 204 antwortet, liefert die API automatisch die gespeicherten Nachrichten nach. Benachrichtigungen, die älter als 7 Tage sind, werden verworfen und können nicht wiederhergestellt werden.

Zurück
Universelle Links und App-Links
Weiter
Fehlerbehebung