Com a API Google Health, seu aplicativo recebe notificações em tempo real quando os dados de saúde de um usuário mudam. Em vez de fazer polling para mudanças, seu servidor recebe uma solicitação HTTPS POST (webhook) assim que os dados ficam disponíveis na API Google Health.
Tipos de dados compatíveis
As notificações de webhook são compatíveis com os seguintes tipos de dados:
- Minutos na faixa ativa
- Altitude
- Gordura corporal
- Calorias na faixa de frequência cardíaca
- Variabilidade da frequência cardíaca diária
- Zonas de frequência cardíaca diárias
- Saturação de oxigênio diária
- Frequência cardíaca em repouso diária
- Derivações diárias da temperatura do sono
- Distância
- Exercício
- Andares
- Frequência cardíaca
- Sono
- Etapas
- Total de calorias
- Peso
As notificações são enviadas para esses tipos de dados somente quando um usuário dá consentimento para um dos escopos correspondentes:
- Atividade, que abrange tipos de dados de passos, altitude, distância e andares:
https://www.googleapis.com/auth/googlehealth.activity_and_fitnesshttps://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
- Métricas de saúde, que abrangem o tipo de dados de peso:
https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurementshttps://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
- Sono, que abrange o tipo de dados de sono:
https://www.googleapis.com/auth/googlehealth.sleephttps://www.googleapis.com/auth/googlehealth.sleep.readonly
Gerenciar inscritos
Antes de receber notificações, é necessário registrar um assinante, que
representa o endpoint de notificação do seu aplicativo. É possível gerenciar assinantes
usando a API REST disponível em
projects.subscribers.
O endpoint do assinante precisa usar HTTPS (TLSv1.2+) e estar acessível ao público.
Durante a criação e as atualizações de assinantes, a API Google Health realiza um desafio de verificação para garantir que você é o proprietário do URI do endpoint. Se a verificação falhar, as operações de criação e atualização de assinantes vão falhar com um FailedPreconditionException.
Criar um assinante
Para registrar um novo assinante no seu projeto, use o endpoint
create. Você precisa informar:
project-id: o número do projeto em que a conta de serviço do webhook foi criada.subscriberId: um identificador exclusivo fornecido por você para o assinante. Ele precisa ter entre 4 e 36 caracteres e corresponder à expressão regular ([a-z]([a-z0-9-]{2,34}[a-z0-9])).endpointUri: o URL de destino das notificações de webhook.subscriberConfigs: os tipos de dados para os quais você quer receber notificações e a política de assinatura de cada um.endpointAuthorization: o mecanismo de autorização do endpoint. Ele precisa conter umsecretque você fornece. O valor desecreté enviado no cabeçalhoAuthorizationcom cada mensagem de notificação. Você pode usar esse token para verificar se as solicitações recebidas são da API Google Health. Por exemplo, você pode definirsecretcomoBearer R4nd0m5tr1ng123para autenticação de portador ouBasic dXNlcjpwYXNzd29yZA==para autenticação básica.
Em subscriberConfigs, defina subscriptionCreatePolicy para cada tipo de dados. Defina como AUTOMATIC para usar assinaturas automáticas ou MANUAL se você
pretende gerenciar as assinaturas dos usuários por conta própria. Consulte assinaturas automáticas e assinaturas manuais para mais detalhes sobre cada opção.
Solicitação
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"
}
}Resposta
{
"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"
}
]
}Listar inscritos
Use o endpoint list para recuperar todos os assinantes registrados no seu projeto.
Solicitação
GET https://health.googleapis.com/v4/projects/project-id/subscribers
Resposta
{
"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
}Atualizar um assinante
Use o endpoint patch
para atualizar um assinante no seu projeto. Os campos que podem ser atualizados são endpointUri, subscriberConfigs e endpointAuthorization.
Para atualizar campos, forneça um parâmetro de consulta updateMask e um corpo da solicitação. O updateMask precisa conter uma lista separada por vírgulas de nomes de campos que você quer atualizar, usando camel case para nomes de campos (por exemplo, endpointUri). O corpo da solicitação precisa conter um objeto Subscriber parcial com os novos valores dos campos que você quer atualizar. Somente os campos especificados em updateMask são atualizados. Se você fornecer campos no corpo da solicitação que não estão em updateMask, eles serão ignorados.
Se você atualizar endpointUri ou endpointAuthorization, a verificação de endpoints será
realizada. Consulte Verificação de endpoints para mais detalhes.
Ao atualizar subscriberConfigs, observe que é uma substituição completa, não uma
fusão. Se subscriberConfigs estiver incluído em updateMask, todas as configurações armazenadas para esse assinante serão substituídas pela lista fornecida no corpo da solicitação. Para adicionar ou remover uma configuração, forneça o conjunto completo de
configurações. Se você estiver atualizando outros campos e quiser manter as configurações atuais, omita subscriberConfigs de updateMask.
Solicitação
PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id?updateMask=endpointUri
{
"endpointUri": "https://myapp.com/new-webhooks/health"
}Resposta
{
"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"
}
]
}Excluir um assinante
Use o endpoint delete
para remover um assinante do seu projeto. Depois de excluído, o assinante
não vai mais receber notificações.
Solicitação
DELETE https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id
Resposta
Um corpo de resposta vazio com o status HTTP "200 OK" será retornado se a exclusão for bem-sucedida.{}Verificação de endpoints
Para garantir a segurança e a confiabilidade da entrega de notificações, a API Google Health realiza um handshake obrigatório de verificação em duas etapas sempre que você cria um assinante ou atualiza a configuração do endpoint (endpointUri ou endpointAuthorization). Esse processo é realizado de forma síncrona durante a chamada de API. O serviço envia duas solicitações POST automatizadas para o URI do endpoint,
usando o User-Agent Google-Health-API-Webhooks-Verifier, com o corpo JSON
{"type": "verification"}.
- Handshake autorizado: a primeira solicitação é enviada com o cabeçalho
Authorizationconfigurado. O servidor precisa responder com um status200 OKou201 Created. - Desafio não autorizado: a segunda solicitação é enviada sem credenciais.
O servidor precisa responder com um status
401 Unauthorizedou403 Forbidden.
Esse handshake confirma que seu endpoint está ativo e aplicando a segurança corretamente. Se qualquer uma das etapas falhar, a solicitação de API vai falhar com um erro
FAILED_PRECONDITION. Somente depois que esse handshake for concluído, seu
assinante será salvo e ativado para receber notificações de dados de saúde.
Rotação de chaves
Se você precisar girar as chaves do endpointAuthorization, siga estas etapas:
- Configure seu endpoint para aceitar valores
endpointAuthorizationantigos e novos. - Atualize a configuração do assinante com o novo valor
endpointAuthorizationusando uma solicitaçãopatchcom?updateMask=endpointAuthorization. - Configure seu endpoint para aceitar apenas o novo valor
endpointAuthorizationdepois de confirmar que a etapa 2 foi concluída.
Assinaturas de usuários
A API Google Health ajuda você a gerenciar as assinaturas dos usuários de maneira eficiente, reduzindo a necessidade de registro manual durante a integração de usuários.
Assinaturas automáticas
Recomendamos usar assinaturas automáticas. Para ativar esse recurso, defina
subscriptionCreatePolicy como AUTOMATIC no seu subscriberConfigs para os
tipos de dados específicos. O dataTypes especificado com uma política AUTOMATIC são os mesmos tipos de dados para os quais a API Google Health envia notificações, desde que o consentimento do usuário também seja concedido para esses tipos de dados.
Quando um usuário concede consentimento do aplicativo para escopos que correspondem a tipos de dados com uma política AUTOMATIC, a API Google Health rastreia e envia automaticamente notificações para os tipos de dados resultantes da interseção entre os tipos de dados consentidos pelo usuário e os tipos de dados de configuração automática do assinante para esse usuário. As notificações são enviadas ao seu endpoint
sempre que o usuário gera novos dados para esses tipos. Isso funciona para usuários que
dão consentimento antes ou depois da criação do assinante. As notificações não são preenchidas com dados gerados antes da criação do assinante.
Se um usuário revogar o consentimento, as notificações para os tipos de dados correspondentes serão interrompidas. As assinaturas automáticas são gerenciadas pelo Google e não podem ser listadas ou excluídas individualmente. Elas só são removidas quando o assinante principal é excluído.
Assinaturas manuais
Se você preferir gerenciar as assinaturas de cada usuário manualmente, defina subscriptionCreatePolicy como MANUAL em subscriberConfigs. Com essa política, as assinaturas de usuários não são criadas automaticamente. Essa funcionalidade será
usada no futuro quando as APIs para gerenciar assinaturas manuais forem
disponibilizadas. Até que essas APIs estejam disponíveis, recomendamos usar as assinaturas do AUTOMATIC.
Notificações
Quando os dados de um usuário mudam para um tipo de dados inscrito, a API Google Health envia uma solicitação POST HTTPS para o URL do endpoint do assinante.
Formato da notificação
O payload da notificação é um objeto JSON que contém detalhes sobre a mudança nos dados. Isso inclui o ID do usuário, o tipo de dados e os intervalos de tempo, que podem ser usados para consultar os dados atualizados.
{
"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"
}
}
]
}
}
O campo operation indica o tipo de mudança que acionou a notificação:
UPSERT: enviado para qualquer adição ou modificação de dados.DELETE: enviado quando um usuário exclui dados ou quando eles são removidos devido a um evento do sistema, como a revogação de permissão ou a exclusão da conta de um usuário.
Recomendamos que você torne a lógica de processamento de notificações idempotente, principalmente para
operações UPSERT, já que as novas tentativas podem causar o envio de notificações duplicadas.
O campo clientProvidedSubscriptionName é um identificador exclusivo. Para
assinaturas com uma política MANUAL, esse campo contém o nome persistente
fornecido pelo desenvolvedor especificado quando a assinatura é criada.
Isso fornece um ID estável para gerenciar assinaturas manuais. Para assinaturas criadas com uma política AUTOMATIC, a API Google Health gera e atribui automaticamente um identificador exclusivo (um UUID aleatório) a esse campo para cada notificação. Incluir clientProvidedSubscriptionName em políticas manuais e automáticas garante um formato de payload de notificação consistente em todos os tipos de assinatura.
O healthUserId é um identificador da API Google Health para o usuário cujos dados foram alterados. Se o aplicativo for compatível com vários usuários, você poderá receber
notificações de qualquer usuário que tenha concedido consentimento ao aplicativo. Quando
você receber uma notificação, use healthUserId para identificar os dados de qual usuário
foram alterados. Assim, você pode usar as credenciais OAuth dele para consultar os dados.
Para mapear as credenciais OAuth de um usuário para o healthUserId, use o endpoint
getIdentity. Chame esse endpoint com as credenciais de um usuário durante a integração para recuperar o healthUserId dele e armazene esse mapeamento. Esse mapeamento não muda com o tempo, então pode ser armazenado em cache indefinidamente. Para um exemplo, consulte
Receber o User ID. Isso permite selecionar as credenciais de usuário corretas ao consultar dados com base no healthUserId em uma notificação.
Responder a uma notificação
Seu servidor precisa responder às notificações imediatamente com um código de status HTTP 204 No Content. Para evitar tempos limite, processe o payload da notificação
de forma assíncrona após enviar a resposta. Se a API Google Health receber qualquer outro código de status ou se a solicitação expirar, ela tentará enviar a notificação novamente mais tarde.
Exemplo de 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
});
});
Status e recuperação de inscritos
Se o endpoint do assinante ficar indisponível ou retornar um código de status de erro (qualquer coisa diferente de 204), a API Google Health vai armazenar notificações pendentes por até sete dias e tentar entregar de novo com espera exponencial.
Quando o endpoint volta a ficar on-line e responde com 204, a API
entrega automaticamente o backlog de mensagens armazenadas. As notificações com mais de sete dias são descartadas e não podem ser recuperadas.