Webhook-Abos

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

Unterstützte Datentypen

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

  • Aktivzonen­minuten
  • Aktivitätslevel
  • Höhe
  • Blutzucker
  • Körperfett
  • Kalorien in Herzfrequenzzone
  • Tägliche Herzfrequenzvariabilität
  • Tägliche Herzfrequenzzonen
  • Tägliche Sauerstoffsättigung
  • Tägliche Atemfrequenz
  • Tägliche Ruheherzfrequenz
  • Tägliche Ableitungen der Schlaftemperatur
  • Entfernung
  • Training
  • Stockwerke
  • Herzfrequenz
  • Herzfrequenzvariabilität
  • Höhe
  • Flüssigkeitszufuhr-Protokoll
  • Ernährungsprotokoll
  • Zusammenfassung der Atemfrequenz im Schlaf
  • Maximale Sauerstoffaufnahme bei Lauf
  • Sitzende Zeit
  • Schlaf
  • Schritte
  • Zeit in Herzfrequenzzone
  • Gewicht

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

  • Aktivität, einschließlich der Datentypen Schritte, Höhe, Entfernung und Stockwerke:
    • https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
    • https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
  • Gesundheitsmesswerte, einschließlich des Datentyps Gewicht:
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.writeonly
  • Schlaf, einschließlich des Datentyps Schlaf:
    • https://www.googleapis.com/auth/googlehealth.sleep.readonly
    • https://www.googleapis.com/auth/googlehealth.sleep.writeonly

IAM-Dienstkonten

Obwohl nicht erforderlich, empfehlen wir, bei der Konfiguration von Abonnenten für die Google Health API ein IAM-Dienstkonto zu verwenden. Dienstkonten bieten im Vergleich zu Standardnutzerkonten eine bessere Sicherheit für Anwendungsworkloads. Das liegt an den folgenden Funktionen:

  • Automatisierte kurzlebige Anmeldedaten:Wenn Dienstkonten mit einer Google Cloud-Ausführungsumgebung (z. B. Compute Engine, Cloud Run oder Google Kubernetes Engine) verknüpft sind, werden automatisch sichere, kurzlebige Anmeldedaten abgerufen und rotiert. So werden die Risiken der Verwaltung und Speicherung von nichtflüchtigen statischen Schlüsseln vermieden.
  • Prinzip der geringsten Berechtigung:Dienstkonten bieten dedizierte Identitäten für Workloads. Sie können ihnen nur die spezifischen Berechtigungen gewähren, die zum Verwalten von Abonnentenendpunkten erforderlich sind. So wird ein umfassenderer Zugriff auf Ihre Google Cloud-Ressourcen vermieden.
  • Unabhängigkeit vom Lebenszyklus:Dienstkonten funktionieren unabhängig vom Konto eines einzelnen Nutzers. So wird sichergestellt, dass sich Personaländerungen nicht auf die langfristige Authentifizierungsstabilität auswirken.

Dienstkonto einrichten

So konfigurieren Sie Ihre Abonnentenanwendung für die Authentifizierung mit einem Dienstkonto:

  1. Dienstkonto erstellen: Rufen Sie in der Google Cloud Console die Seite „IAM und Verwaltung“ Ihres Projekts auf, um ein neues nutzerverwaltetes Dienstkonto zu erstellen.
  2. Erforderliche IAM-Rollen zuweisen: Weisen Sie dem Dienstkonto die entsprechenden Rollen zu, die zum Verwalten von Abonnenten in Ihrem Google Cloud-Projekt erforderlich sind.
  3. Dienstkonto mit Ihrem Workload verknüpfen:Konfigurieren Sie die Umgebung, in der Ihre Abonnentenlogik gehostet wird, so, dass sie als das neue Dienstkonto ausgeführt wird. So kann Ihr Anwendungscode (z. B. Google API-Clientbibliotheken) die kurzlebigen Anmeldedaten des Dienstkontos automatisch erkennen und verwenden, wenn die projects.subscribers REST API aufgerufen wird.

CPE-Rollen

Wenn Sie Abonnenten oder Abos der Google Health API verwalten möchten, müssen Sie dem imitierten Dienstkonto, das die API-Aufrufe ausführt, die entsprechende Rolle zuweisen. Weisen Sie je nach erforderlichem Zugriff eine der folgenden Rollen zu:

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

Weitere Informationen zu IAM-Rollen und ‑Berechtigungen der Google Health API.

Abonnenten verwalten

Bevor Sie Benachrichtigungen erhalten können, müssen Sie einen Abonnenten registrieren, der den Benachrichtigungsendpunkt Ihrer Anwendung darstellt. Sie können Abonnenten mit der 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 Überprüfung durch, um sicherzustellen, dass Sie der Inhaber des Endpunkt-URI sind. Wenn die Überprüfung fehlschlägt, schlagen die Vorgänge zum Erstellen und Aktualisieren von Abonnenten mit einer FailedPreconditionException fehl.

Abonnent erstellen

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

  • project-id: Die Projektnummer, unter der das Webhook-Dienstkonto erstellt wurde.
  • subscriberId: Eine eindeutige ID, 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.
  • 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 Datentyp.
  • endpointAuthorization: Der Autorisierungsmechanismus für Ihren Endpunkt. Dieser muss ein von Ihnen bereitgestelltes secret enthalten. Der Wert von secret wird in 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 secret beispielsweise auf Bearer R4nd0m5tr1ng123 für die Bearer-Authentifizierung oder auf Basic dXNlcjpwYXNzd29yZA== für die Basisauthentifizierung festlegen.

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

Antwort

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

Abonnenten auflisten

Verwenden Sie den Endpunkt list , um alle für Ihr Projekt registrierten Abonnenten abzurufen.

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",
      "subscriberConfigs": [
        {
          "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
          "subscriptionCreatePolicy": "AUTOMATIC"
        },
        {
          "dataTypes": ["sleep"],
          "subscriptionCreatePolicy": "MANUAL"
        }
      ],
      "endpointAuthorization": {
        "authorizationTokenSet": true
      }
    }
  ],
  "totalSize": 1
}

Abonnent aktualisieren

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

Sie aktualisieren Felder, indem Sie einen Abfrageparameter updateMask und einen Anfragetext angeben. updateMask muss eine durch Kommas getrennte Liste der Feldnamen enthalten, die Sie aktualisieren möchten. Verwenden Sie für Feldnamen Camel Case (z. B. endpointUri). Der Anfragetext muss ein teilweises Abonnentenobjekt 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, dass es sich bei der Aktualisierung von subscriberConfigs 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 die vollständige Konfiguration 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",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ]
}

Abonnent löschen

Verwenden Sie den delete Endpunkt, 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 war, wird ein leerer Antworttext mit dem HTTP-Status `200 OK` zurückgegeben. 
{}

Endpunktprüfung

Um die Sicherheit und Zuverlässigkeit der Benachrichtigungszustellung zu gewährleisten, führt die Google Health API bei jedem Erstellen eines Abonnenten oder Aktualisieren der Endpunktkonfiguration (endpointUri oder endpointAuthorization) einen obligatorischen zweistufigen Überprüfungshandshake durch. Dieser Vorgang 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, mit 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 Herausforderung: Die zweite Anfrage wird ohne Anmeldedaten gesendet. Ihr Server muss mit dem Status 401 Unauthorized oder 403 Forbidden antworten.

Dieser Handshake bestätigt, dass Ihr Endpunkt aktiv ist und die Sicherheit korrekt durchsetzt. Wenn einer der Schritte fehlschlägt, schlägt die API-Anfrage mit dem Fehler FAILED_PRECONDITION fehl. Erst wenn dieser Handshake erfolgreich ist, wird Ihr 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 sowohl alte als auch neue endpointAuthorization-Werte akzeptiert werden.
  2. Aktualisieren Sie die Abonnentenkonfiguration mit dem neuen endpointAuthorization-Wert . Verwenden Sie dazu eine patch-Anfrage mit ?updateMask=endpointAuthorization.
  3. Konfigurieren Sie Ihren Endpunkt so, dass nur der neue endpointAuthorization-Wert akzeptiert wird, nachdem Sie bestätigt haben, dass Schritt 2 erfolgreich war.

Nutzerabos

Mit der Google Health API können Sie Nutzerabos effizient verwalten. So ist keine manuelle Registrierung beim Onboarding von Nutzern erforderlich.

Automatische Abos

Wir empfehlen, automatische Abos zu verwenden. Wenn Sie diese Funktion aktivieren möchten, legen Sie subscriptionCreatePolicy in subscriberConfigs für die jeweiligen Datentypen auf AUTOMATIC fest. Die mit einer AUTOMATIC-Richtlinie angegebenen dataTypes sind dieselben Datentypen, für die die Google Health API Benachrichtigungen sendet, sofern auch die Nutzereinwilligung für diese Datentypen erteilt wurde.

Wenn ein Nutzer die Einwilligung für Bereiche erteilt, die Datentypen mit einer AUTOMATIC-Richtlinie entsprechen, erfasst die Google Health API automatisch die Datentypen, die sich aus der Schnittmenge zwischen den vom Nutzer genehmigten Datentypen und den Datentypen der automatischen Abonnentenkonfiguration für diesen Nutzer ergeben, und sendet Benachrichtigungen für diese Datentypen. Benachrichtigungen werden dann an Ihren Endpunkt gesendet, wenn dieser Nutzer neue Daten für diese Typen generiert. Das funktioniert für Nutzer, die ihre Einwilligung erteilen, bevor oder nachdem Sie den Abonnenten erstellt haben. Benachrichtigungen werden nicht für Daten gesendet, 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 Ihr Abonnent mit einer MANUAL-subscription_create_policy für bestimmte Datentypen konfiguriert ist, müssen Sie Abos für jeden Nutzer explizit erstellen und verwalten. Ein Abo verknüpft einen bestimmten Nutzer mit Ihrem Abonnentenendpunkt für eine definierte Gruppe von Datentypen. Entwickler können bestimmte APIs verwenden, um Folgendes zu tun:

  • Manuelle Abos pro healthUserId erstellen: Erstellt ein neues Abo für einen bestimmten Nutzer. Für diese Methode muss für den Abonnenten eine SubscriptionCreatePolicy auf MANUAL für die angeforderten Datentypen festgelegt sein.
  • Manuelle Abos aktualisieren: Aktualisiert die Datentypen für ein vorhandenes Nutzerabo.
  • Manuelle Abos löschen: Löscht ein bestimmtes Nutzerabo. Nach dem Löschen erhält Ihr Abonnentenendpunkt keine Benachrichtigungen mehr für diesen Nutzer für die zugehörigen Datentypen.
  • Manuelle Abos auflisten: Listet alle aktiven Abos für einen bestimmten Abonnenten auf. Sie können die Ergebnisse nach Nutzer oder Datentyp filtern.

Benachrichtigungen

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

Benachrichtigungsformat

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

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

  • UPSERT: Wird bei jeder Datenhinzufügung oder ‑änderung gesendet.
  • DELETE: Wird gesendet, wenn ein Nutzer Daten löscht.

Wir empfehlen, die Logik zur Benachrichtigungsbehandlung idempotent zu gestalten, insbesondere für UPSERT-Vorgänge, da Wiederholungen dazu führen können, dass doppelte Benachrichtigungen gesendet werden.

Das Feld clientProvidedSubscriptionName ist eine eindeutige ID. Bei Abos mit einer MANUAL-Richtlinie enthält dieses Feld den nichtflüchtigen, vom Entwickler bereitgestellten Abo-Namen, der beim Erstellen des Abos angegeben wurde. So erhalten Sie eine stabile ID für die Verwaltung manueller Abos. Bei Abos, die mit einer AUTOMATIC-Richtlinie erstellt wurden, generiert und weist die Google Health API diesem Feld für jede Benachrichtigung automatisch eine eindeutige ID (eine zufällige UUID) zu. Wenn Sie clientProvidedSubscriptionName sowohl für manuelle als auch für automatische Richtlinien angeben, wird ein einheitliches Format für die Benachrichtigungsnutzlast für alle Abo-Typen gewährleistet.

healthUserId ist eine Google Health API-ID 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 zu ermitteln, wessen Daten sich geändert haben. So können Sie die OAuth-Anmeldedaten des Nutzers verwenden, um seine Daten abzufragen.

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

Aggregation von Updates

Um den Netzwerkverkehr zu minimieren, werden Nachrichten in der Google Health API zusammengefasst. Das System ist so konfiguriert, dass maximal 99 Nachrichten pro Batch gesendet werden. Diese werden automatisch per Push übertragen, sobald sie verfügbar sind.

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 die Anfrage eine Zeitüberschreitung verursacht, 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
    });
});

Es gibt drei gängige Strategien zum Aktualisieren Ihrer Datenbank nach dem Empfang einer Benachrichtigung über eine Datenänderung:

  • Warteschlange (empfohlen): Platzieren Sie die eingehenden Benachrichtigungen in einer Nachrichten warteschlange und verarbeiten Sie sie basierend auf den Systemressourcen.
  • Sofortiger Abruf: Weisen Sie Ihr Back-End an, sofort die Google Health API aufzurufen, um die aktualisierten Daten abzurufen und in Ihrer Datenbank zu speichern.
  • Verzögerte Updates: Markieren Sie die lokalen Datenbankeinträge des Nutzers als veraltet und rufen Sie die aktualisierten Daten erst dann von der Google Health API ab, wenn der Nutzer Ihre Anwendung das nächste Mal aufruft.

Mit der Warteschlangenstrategie können Sie Daten nahezu in Echtzeit verarbeiten und gleichzeitig widerstandsfähig gegen eine Flut von Benachrichtigungen bleiben (z. B. wenn ein Dienstausfall dazu führt, dass ein Rückstand an Benachrichtigungen auf einmal zugestellt wird). Sie können diese Warteschlangen zwar in einem Batch-Zeitplan mit langen Intervallen (z. B. alle 3 Stunden) verarbeiten, um Ressourcen zu sparen. Der Nachteil ist jedoch, dass Nutzer in der Regel erwarten, dass ihre Daten nahezu in Echtzeit aktualisiert werden.

Best Practices

Beachten Sie diese Best Practices, um eine zuverlässige und effiziente Verarbeitung von Datenaktualisierungen zu gewährleisten:

  • Subscription API verwenden: Verwenden Sie die Subscription API, um benachrichtigt zu werden, wenn ein Nutzer neue Daten zum Herunterladen hat, anstatt Endpunkte abzufragen.
  • Benachrichtigungen in die Warteschlange stellen und separat verarbeiten: Wenn Sie Abo- Benachrichtigungen erhalten, stellen Sie sie in eine Warteschlange und verarbeiten Sie sie separat basierend auf den Ressourcen Ihres Systems. Halten Sie den Webhook-Endpunkt schlank, indem Sie die Anfrage sofort bestätigen.

Signaturüberprüfung

Um die Authentizität von Webhook-Benachrichtigungen zu gewährleisten, wird die Roh-JSON-Nutzlast jeder ausgehenden Webhook-Benachrichtigung mit einem privaten Schlüssel mit PublicKeySign von Tink signiert. Die Base64-codierte Signatur wird im GOOGLE-HEALTH-API-SIGNATURE HTTP-Header in der Anfrage bereitgestellt. Diese Signaturschlüssel werden alle 30 Tage automatisch rotiert. Der entsprechende offizielle öffentliche Schlüsselsatz wird als JSON-Datei unter der permanenten URL https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json verteilt.

Signatur überprüfen

Mit Tink (empfohlen): Entwickler können die Signatur mit dem PublicKeyVerify -Primitiv von Tink überprüfen. Rufen Sie den öffentlichen Schlüsselsatz von der permanenten URL ab, instanziieren Sie das PublicKeyVerify-Primitiv mit dem Schlüsselsatz und überprüfen Sie den decodierten GOOGLE-HEALTH-API-SIGNATURE-Header anhand der Roh-Webhook-JSON-Nutzlast.

Manuelle Überprüfung (ohne Tink): Wenn Entwickler Tink nicht verwenden möchten, können sie die Signatur manuell überprüfen. Gehen Sie dazu so vor:

  1. Decodieren Sie den GOOGLE-HEALTH-API-SIGNATURE-Header mit Base64, um das 5-Byte-Tink-Präfix (mit einem 1-Byte-Versionspräfix und einer 4-Byte-keyId) von der eigentlichen DER-codierten Signatur zu trennen.
  2. Rufen Sie den JSON-Schlüsselsatz unter https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json ab.
  3. Suchen Sie den Schlüssel, der der geparsten keyId entspricht, und decodieren Sie das Wertfeld mit Base64. Es enthält einen serialisierten EcdsaPublicKey-Protokollpuffer.
  4. Extrahieren Sie die Big-Endian-Koordinaten x und y (Protobuf-Tags 3 und 4) aus dieser binären Nutzlast.
  5. Instanziieren Sie mit den extrahierten x- und y-Koordinaten einen standardmäßigen öffentlichen ECDSA P-256-Schlüssel in einer integrierten Kryptografiebibliothek.
  6. Überprüfen Sie die Roh-Webhook-JSON-Nutzlast anhand der extrahierten DER-Signatur mit dem SHA-256-Algorithmus.

Abonnentenstatus und ‑wiederherstellung

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

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

Häufige Fehler

Fehlercode Nachricht Beschreibung Empfehlung
400 Fehlerhafte Anfrage Ungültige Projektnummer im Ressourcennamen Beim Löschen oder Aktualisieren eines Abonnenten wird anstelle der Projektnummer die Google Cloud-Projekt-ID in der Anfrage-URL verwendet. Dies gilt für Webhook-Abos mit dem Endpunkt projects.subscribers. Verwenden Sie in der Anfrage-URL Ihre Google Cloud-Projektnummer und nicht die Projekt-ID.
403 Verboten Das Dienstkonto hat keine Berechtigung. Beim Erstellen oder Auflisten von Abonnenten wird anstelle der Projektnummer die Google Cloud-Projekt-ID in der Anfrage-URL verwendet. Dies gilt für Webhook-Abos mit dem Endpunkt projects.subscribers. Verwenden Sie in der Anfrage-URL Ihre Google Cloud-Projektnummer und nicht die Projekt-ID.

Zurück
Universelle Links und App-Links
Weiter
Fehlerbehebung