Google Health API webhooks: subscribers, verification and notifications

Notifications are sent for these data types only when a user has granted consent for one of the corresponding scopes:

• Activity, which covers active minutes, steps, altitude, distance, and floors data types:
  • https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
  • https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
• Health Metrics, which covers the weight data type:
  • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
  • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.writeonly
• Sleep, which covers the sleep data type:
  • https://www.googleapis.com/auth/googlehealth.sleep.readonly
  • https://www.googleapis.com/auth/googlehealth.sleep.writeonly

Before you can receive notifications, you must register a Subscriber, which represents your application's notification endpoint. You can manage subscribers using the REST API available at projects.subscribers.

Your subscriber endpoint must use HTTPS (TLSv1.2+) and be publicly accessible. During subscriber creation and updates, the Google Health API performs a verification challenge to ensure you own the endpoint URI. If verification fails, subscriber creation and update operations fail with a FailedPreconditionException.

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

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

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

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

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

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

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

{}

While not required, we recommend using an IAM Service Account when configuring subscribers for the Google Health API. Service accounts provide better security for application workloads compared to standard user accounts through the following features:

• Automated short-lived credentials: When attached to a Google Cloud execution environment (such as Compute Engine, Cloud Run, or Google Kubernetes Engine), service accounts automatically obtain and rotate secure, short-lived credentials. This removes the risks of managing and storing persistent static keys.
• Principle of least privilege: Service accounts provide dedicated identities for workloads. You can grant them only the specific permissions needed to manage subscriber endpoints, avoiding broader access to your Google Cloud resources.
• Lifecycle independence: Service accounts operate independently of any individual user's account, ensuring that personnel changes don't impact long-term authentication stability.

To manage Google Health API Subscribers or Subscriptions, you must grant the appropriate role to the impersonated Service Account making the API calls. Depending on the level of access needed, assign one of the following roles:

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

Learn more about Google Health API IAM roles and permissions.

To ensure the security and reliability of your notification delivery, the Google Health API performs a mandatory two-step verification handshake whenever you create a subscriber or update its endpoint configuration (endpointUri or endpointAuthorization). This process is performed synchronously during the API call. The service sends two automated POST requests to your endpoint URI, using the User-Agent Google-Health-API-Webhooks, with the JSON body {"type": "verification"}.

• Authorized Handshake: The first request is sent with your configured Authorization header. Your server must respond with a 200 OK or 201 Created status.
• Unauthorized Challenge: The second request is sent without credentials. Your server must respond with a 401 Unauthorized or 403 Forbidden status.

This handshake confirms that your endpoint is active and correctly enforcing security. If either step fails, the API request fails with a FAILED_PRECONDITION error. Only after this handshake succeeds is your subscriber saved and activated to receive health data notifications.

The Google Health API helps you manage user subscriptions efficiently, reducing the need for manual registration during user onboarding.

The notification payload contains details about the data change, including the user ID, data type, and time intervals, which you can use to query the updated data. When multiple updates occur or updates are aggregated, notifications are batched together and delivered as a JSON array of notification objects.

When a webhook notification is triggered, the Google Health API sends an HTTPS POST request to your subscriber endpoint with the following format:

POST https://your-endpoint-uri
Authorization: Bearer example-secret-token
GOOGLE-HEALTH-API-SIGNATURE: signature-value
Content-Type: application/json

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

POST https://your-endpoint-uri
Authorization: Bearer example-secret-token
GOOGLE-HEALTH-API-SIGNATURE: signature-value
Content-Type: application/json

[
  {
    "data": {
      "version": "1",
      "clientProvidedSubscriptionName": "subscription-name",
      "healthUserId": "health-user-id",
      "operation": "DELETE",
      "dataType": "steps",
      "intervals": [
        {
          "physicalTimeInterval": {
            "startTime": "2026-08-12T12:00:00Z",
            "endTime": "2026-08-12T12:30:00Z"
          },
          "civilIso8601TimeInterval": {
            "startTime": "2026-08-12T12:00:00",
            "endTime": "2026-08-12T12:30:00"
          }
        }
      ]
    }
  }
]

POST https://your-endpoint-uri
Authorization: Bearer example-secret-token
GOOGLE-HEALTH-API-SIGNATURE: signature-value
Content-Type: application/json

{
  "data": {
    "version": "1",
    "clientProvidedSubscriptionName": "subscription-name",
    "healthUserId": "health-user-id",
    "operation": "DELETE",
    "dataType": "sleep",
    "intervals": [
      {
        "physicalTimeInterval": {
          "startTime": "2026-08-12T22:00:00Z",
          "endTime": "2026-08-13T06:00:00Z"
        },
        "civilIso8601TimeInterval": {
          "startTime": "2026-08-12T22:00:00",
          "endTime": "2026-08-13T06:00:00"
        }
      }
    ],
    "recordId": "9875412"
  }
}

The operation field indicates the type of change that triggered the notification:

• UPSERT: Sent for any data addition or modification.
• DELETE: Sent when a user explicitly deletes data (such as deleting dataPoints using the Fitbit app or performing a batch delete using the API). Webhook notifications are not sent for system-level deletion events, such as a user revoking application permissions or deleting their Fitbit account.

We recommend making your notification handling logic idempotent, especially for UPSERT operations, as retries can cause duplicate notifications to be sent.

The clientProvidedSubscriptionName field is a unique identifier:

• For subscriptions with a MANUAL policy, this field contains the persistent, developer-provided subscription name specified when the subscription is created. This provides a stable ID for managing manual subscriptions.
• For subscriptions created with an AUTOMATIC policy, the Google Health API automatically generates and assigns an identifier in the format: auto-<project-number>-<subscriber-id>-<WEBHOOK_DATA_TYPE_TOKEN>, where:
  • <project-number> is the developer's Google Cloud project number (for example, 362978535920).
  • <subscriber-id> is the subscriber's registration ID / subscriber name (for example, google-health-sync).
  • <WEBHOOK_DATA_TYPE_TOKEN> is the token representing the specific data type. See Vocabulary of webhook data type tokens for all possible tokens.

Including clientProvidedSubscriptionName for both manual and automatic policies ensures a consistent notification payload format across all subscription types.

The healthUserId is a Google Health API identifier for the user whose data has changed. If your application supports multiple users, you can receive notifications for any user who has granted your application consent. When you receive a notification, use healthUserId to identify which user's data has changed, so you can use their OAuth credentials to query their data.

To map a user's OAuth credentials to their healthUserId, use the getIdentity endpoint. Call this endpoint with a user's credentials during user onboarding to retrieve their healthUserId, and store this mapping. This mapping doesn't change over time, so it can be cached indefinitely. For an example, see Get user ID. This lets you select the correct user credentials when querying data based on the healthUserId in a notification.

The intervals array contains one or more objects representing the time intervals for the modified data:

For full-day activities and daily aggregates, the physicalTimeInterval field is intentionally omitted from the notification payload. This is because full-day events are bucketed by their nominal civil date, and physical time durations can be inaccurate when crossing timezones. When processing full-day events, you should rely on the civilDateTimeInterval or civilIso8601TimeInterval fields as a best practice. For details on how to query these data points using civil time filters, see Filter data by an interval civil start time.

The following is an example notification payload for a full-day activity where the physicalTimeInterval field is omitted:

{
  "data": {
    "version": "1",
    "clientProvidedSubscriptionName": "auto-503461148219-lindasubscriber-WEBHOOK_DATA_TYPE_STEPS",
    "healthUserId": "343864966078399341",
    "operation": "UPSERT",
    "dataType": "steps",
    "intervals": [
      {
        "civilDateTimeInterval": {
          "startDateTime": {
            "date": {
              "year": 2026,
              "month": 7,
              "day": 14
            },
            "time": {}
          },
          "endDateTime": {
            "date": {
              "year": 2026,
              "month": 7,
              "day": 15
            },
            "time": {}
          }
        },
        "civilIso8601TimeInterval": {
          "startTime": "2026-07-14T00:00:00",
          "endTime": "2026-07-15T00:00:00"
        }
      }
    ]
  }
}

To minimize network traffic, the Google Health API batches messages together. The system is configured to send out a maximum of 99 messages per batch, which are automatically pushed as they become available.

When messages are batched, the payload is delivered as a JSON array containing multiple notification objects. A single batch can include updates for multiple users across multiple subscribed data types. For an example payload, see the Batch (multiple users and data types) example in the Notification format section.

Your server must respond to notifications with an HTTP 204 No Content status code immediately. To avoid timeouts, process the notification payload asynchronously after sending the response. If the Google Health API receives any other status code or the request times out, it retries sending the notification later.

Node.js (Express) Example:

app.post('/webhook-receiver', (req, res) => {
    // 1. Immediately acknowledge the notification batch
    res.status(204).send();

    // 2. Process the data asynchronously in the background
    const notification = req.body;
    setImmediate(() => {
        for (const notification of notifications) {
            console.log(`Update for user ${notification.data.healthUserId} of type ${notification.data.dataType}`);
            // Trigger your data retrieval logic here
        }
    });
});

There are three common strategies for updating your database after receiving a data change notification:

• Queuing (recommended): Place the incoming notifications into a message queue and process them off the queue based on system resources.
• Immediate retrieval: Direct your backend to immediately call the Google Health API to fetch the updated data and commit it to your database.
• Lazy updates: Mark the user's local database records as dirty and only fetch the updated data from the Google Health API when the user next visits your application.

The queueing strategy lets you process data in near real-time while remaining resilient to a flood of notifications (for example, if a service outage causes a backlog of notifications to be delivered all at once). While you can choose to process these queues on a long-interval batch schedule (for example, every 3 hours) to save resources, the drawback is that users typically expect to see their data updated in near real-time.

Follow these best practices to ensure reliable and efficient handling of data updates:

• Use the Subscription API: Use the Subscription API to be notified when a user has new data to download rather than polling endpoints.
• Queue and process notifications separately: When receiving subscription notifications, place them into a queue and process them separately based on your system's resources. Keep the webhook endpoint lightweight by acknowledging the request immediately.

To ensure the authenticity of Webhooks notifications, the raw JSON payload of every outgoing webhook notification is signed with a private key using Tink's PublicKeySign, providing the Base64-encoded signature in the GOOGLE-HEALTH-API-SIGNATURE HTTP header in the request. These signing keys are automatically rotated every 30 days, and the corresponding official public keyset is distributed as a JSON file at the permanent URL https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json.

If your subscriber endpoint becomes unavailable or returns an error status code (anything other than 204), the Google Health API stores pending notifications for up to 7 days and retries delivery with exponential backoff.

Once your endpoint is back online and responds with 204, the API automatically delivers the backlog of stored messages. Notifications older than 7 days are discarded and cannot be recovered.