Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Assinaturas de webhook

A API Google Health permite que seu aplicativo receba notificações em tempo real quando os dados de saúde de um usuário mudam. Em vez de fazer uma pesquisa de mudanças, seu servidor recebe uma solicitação HTTPS POST (webhook){:target="_blank" class="external"} 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
Nível de atividade
Altitude
Glicemia
Gordura corporal
Calorias na faixa de frequência cardíaca
Variabilidade da frequência cardíaca diária
Faixas de frequência cardíaca diárias
Saturação de oxigênio diária
Ritmo respiratório diário
Frequência cardíaca em repouso diária
Derivações diárias de temperatura do sono
Distância
Exercício
Andares
Frequência cardíaca
Variabilidade da frequência cardíaca
Altura
Registro de hidratação
Registro de alimentação
Resumo do ritmo respiratório do sono
VO₂ máx. da corrida
Período sedentário
Sono
Etapas
Tempo na faixa de frequência cardíaca
Total Calories
Peso

As notificações são enviadas para esses tipos de dados somente quando um usuário concede consentimento para um dos escopos correspondentes:

Atividade, que abrange os tipos de dados de etapas, altitude, distância e andares:
- https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
- https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
Métricas de saúde, que abrangem o tipo de dados de peso:
- https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
- https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.writeonly
Sono, que abrange o tipo de dados de sono:
- https://www.googleapis.com/auth/googlehealth.sleep.readonly
- https://www.googleapis.com/auth/googlehealth.sleep.writeonly

Contas de serviço do IAM

Embora não seja obrigatório, recomendamos o uso de uma conta de serviço do IAM ao configurar assinantes para a API Google Health. As contas de serviço oferecem melhor segurança para cargas de trabalho de aplicativos em comparação com as contas de usuário padrão, usando os seguintes recursos:

Credenciais automatizadas de curta duração:quando anexadas a um ambiente de execução do Google Cloud (como o Compute Engine, o Cloud Run ou o Google Kubernetes Engine), as contas de serviço recebem e giram automaticamente credenciais seguras e de curta duração. Isso remove os riscos de gerenciar e armazenar chaves estáticas permanentes.
Princípio do privilégio mínimo:as contas de serviço fornecem identidades dedicadas para cargas de trabalho. Você pode conceder apenas as permissões específicas necessárias para gerenciar endpoints de assinantes, evitando um acesso mais amplo aos recursos do Google Cloud.
Independência do ciclo de vida:as contas de serviço operam de forma independente da conta de qualquer usuário individual, garantindo que as mudanças de pessoal não afetem a estabilidade da autenticação de longo prazo.

Configurar uma conta de serviço

Para configurar o aplicativo de assinante para autenticação usando uma conta de serviço:

Crie uma conta de serviço: no console do Google Cloud, acesse a página "IAM e administrador" do seu projeto para criar uma nova conta de serviço gerenciada pelo usuário.
Conceda os papéis necessários do IAM: atribua à conta de serviço os papéis apropriados necessários para gerenciar assinantes no seu projeto do Google Cloud.
Anexe a conta de serviço à sua carga de trabalho:configure o ambiente que hospeda a lógica do assinante para ser executado como a nova conta de serviço. Isso permite que o código do aplicativo (como as bibliotecas de cliente da API do Google) detecte e use automaticamente as credenciais de curta duração da conta de serviço ao chamar a API REST projects.subscribers.

Papéis do CPE

Para gerenciar assinantes ou assinaturas da API Google Health, conceda o papel apropriado à conta de serviço representada que faz as chamadas de API. Dependendo do nível de acesso necessário, atribua um dos seguintes papéis:

Leitor da API Google Health
Editor da API Google Health
Administrador da API Google Health

Saiba mais sobre os papéis e permissões do IAM da API Google Health.

Gerenciar assinantes

Antes de receber notificações, registre um assinante, que representa o endpoint de notificação do aplicativo. É possível gerenciar assinantes usando a API REST disponível em projects.subscribers.

O endpoint do assinante precisa usar HTTPS (TLSv1.2 ou mais recente) e ser acessível publicamente. Durante a criação e as atualizações do assinante, a API Google Health realiza um desafio de verificação para garantir que você seja o proprietário do URI do endpoint. Se a verificação falhar, as operações de criação e atualização do assinante vão falhar com uma FailedPreconditionException.

Criar um assinante

Para registrar um novo assinante para seu projeto, use o create endpoint. Você precisa fornecer:

project-id: o número do projeto em que a conta de serviço do webhook foi criada.
subscriberId: um identificador exclusivo fornecido para o assinante. Esse ID 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 para notificações de webhook.
subscriberConfigs: os tipos de dados para os quais você quer receber notificações e a política de assinatura para cada um deles.
endpointAuthorization: o mecanismo de autorização do seu endpoint. Ele precisa conter um secret que você fornece. O valor de secret é enviado no cabeçalho Authorization com 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, é possível definir secret como Bearer R4nd0m5tr1ng123 para autenticação de portador ou Basic 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 de usuário. 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 assinantes

Use o list endpoint 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 patch endpoint para atualizar um assinante no seu projeto. Os campos que podem ser atualizados são endpointUri, subscriberConfigs e endpointAuthorization.

Para atualizar os 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 dos nomes dos campos que você quer atualizar, usando camel case para os nomes dos campos (por exemplo, endpointUri). O corpo da solicitação precisa conter um objeto de assinante 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 endpoint será realizada. Consulte Verificação de endpoints para mais detalhes.

Ao atualizar subscriberConfigs, observe que é uma substituição completa, não uma mesclagem. 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 delete endpoint 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 de verificação em duas etapas obrigatório 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 configurado Authorization. Seu servidor precisa responder com um status 200 OK ou 201 Created.
Desafio não autorizado: a segunda solicitação é enviada sem credenciais. Seu servidor precisa responder com um status 401 Unauthorized ou 403 Forbidden.

Esse handshake confirma que o 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 bem-sucedido, o assinante será salvo e ativado para receber notificações de dados de saúde.

Rotação de chaves

Se você precisar girar as chaves para endpointAuthorization, siga estas etapas:

Configure o endpoint para aceitar valores endpointAuthorization antigos e novos.
Atualize a configuração do assinante com o novo valor endpointAuthorization usando uma solicitação patch com ?updateMask=endpointAuthorization.
Configure o endpoint para aceitar apenas o novo valor endpointAuthorization depois de confirmar que a etapa 2 foi bem-sucedida.

Assinaturas do usuário

A API Google Health ajuda a gerenciar assinaturas de usuários com eficiência, reduzindo a necessidade de registro manual durante a integração do usuário.

Assinaturas automáticas

Recomendamos o uso de assinaturas automáticas. Para ativar esse recurso, defina subscriptionCreatePolicy como AUTOMATIC em subscriberConfigs para os tipos de dados específicos. Os dataTypes especificados 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 endpoint sempre que o usuário gera novos dados para esses tipos. Isso funciona para usuários que concedem consentimento antes ou depois de você criar o assinante. As notificações não são preenchidas para 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ão removidas apenas quando o assinante pai é excluído.

Assinaturas manuais

Se o assinante estiver configurado com uma subscription_create_policy MANUAL para tipos de dados específicos, você precisará criar e gerenciar explicitamente as assinaturas de cada usuário. Uma assinatura vincula um usuário específico ao endpoint do assinante para um conjunto definido de tipos de dados. Os desenvolvedores podem usar APIs específicas para:

Criar assinaturas (manuais) por healthUserId: cria uma nova assinatura para um usuário específico. Esse método exige que o assinante tenha uma SubscriptionCreatePolicy definida como MANUAL para os tipos de dados solicitados.
Atualizar a assinatura (manual): atualiza os tipos de dados de uma assinatura de usuário existente.
Excluir a assinatura (manual): exclui uma assinatura de usuário específica. Depois de excluído, o endpoint do assinante não vai mais receber notificações para esse usuário para os tipos de dados associados.
Listar assinaturas (manuais): lista todas as assinaturas ativas de um determinado assinante. É possível filtrar os resultados por usuário ou tipo de dados.

Notificações

Quando os dados de um usuário mudam para um tipo de dados inscrito, a API Google Health envia uma solicitação HTTPS POST para o URL do endpoint do assinante.

Formato da notificação

O payload de notificação é um objeto JSON que contém detalhes sobre a mudança de 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-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"
        }
      }
    ]
  }
}

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.

Recomendamos que você torne a lógica de tratamento de notificações idempotente, especialmente 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 da assinatura 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. A inclusão de clientProvidedSubscriptionName para 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 oferece suporte a 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 do usuário que foram alterados. Assim, você poderá usar as credenciais OAuth dele para consultar os dados.

Para mapear as credenciais OAuth de um usuário para o healthUserId, use o getIdentity endpoint. Chame esse endpoint com as credenciais de um usuário durante a integração para recuperar o healthUserId e armazenar esse mapeamento. Esse mapeamento não muda com o tempo, então ele pode ser armazenado em cache indefinidamente. Para conferir um exemplo, consulte Receber o ID do usuário. 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 com um código de status HTTP 204 No Content imediatamente. Para evitar tempos limite, processe o payload de 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 atingir o tempo limite, ela vai 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
    });
});

Verificação de assinatura

Para garantir a autenticidade das notificações de webhook, o payload JSON bruto de cada notificação de webhook de saída é assinado com uma chave privada usando o PublicKeySign do Tink, fornecendo a assinatura codificada em Base64 no cabeçalho HTTP GOOGLE-HEALTH-API-SIGNATURE na solicitação. Essas chaves de assinatura são giradas automaticamente a cada 30 dias, e o conjunto de chaves públicas oficiais correspondente é distribuído como um arquivo JSON no URL permanente https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json.

Como verificar a assinatura

Usando o Tink (recomendado): os desenvolvedores podem verificar a assinatura usando a primitiva PublicKeyVerify do Tink. Busque o conjunto de chaves públicas no URL permanente, instancie a primitiva PublicKeyVerify com o conjunto de chaves e verifique o cabeçalho GOOGLE-HEALTH-API-SIGNATURE decodificado no payload JSON do webhook bruto.

Verificação manual (sem o Tink): se os desenvolvedores optarem por não usar o Tink, eles poderão verificar a assinatura manualmente seguindo estas etapas:

Decodifica em Base64 o cabeçalho GOOGLE-HEALTH-API-SIGNATURE para separar o prefixo Tink de 5 bytes (que contém um prefixo de versão de 1 byte e um keyId de 4 bytes) da assinatura codificada em DER real.
Busque o conjunto de chaves JSON em https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json.
Localize a chave que corresponde ao keyId analisado e decodifique em Base64 o campo de valor, que contém um buffer de protocolo EcdsaPublicKey serializado.
Extraia as coordenadas x e y de big-endian (tags Protobuf 3 e 4) desse payload binário.
Instancie uma chave pública ECDSA P-256 padrão em uma biblioteca de criptografia integrada usando as coordenadas x e y extraídas.
Verifique o payload JSON do webhook bruto na assinatura DER extraída usando o algoritmo SHA-256.

Status e recuperação de assinantes

Se o endpoint do assinante ficar indisponível ou retornar um código de status de erro (qualquer valor diferente de 204), a API Google Health vai armazenar as notificações pendentes por até 7 dias e tentar entregar novamente com uma espera exponencial.

Quando o endpoint estiver on-line novamente e responder com 204, a API vai entregar automaticamente o backlog de mensagens armazenadas. As notificações com mais de 7 dias serão descartadas e não poderão ser recuperadas.

Erros comuns

Código do erro	Mensagem	Descrição	Recomendação
400 Solicitação inválida	Número de projeto inválido no nome do recurso	Ao excluir ou atualizar um assinante usando o ID do projeto do Google Cloud no URL da solicitação em vez do número do projeto. Isso se aplica a assinaturas de webhook usando o endpoint `projects.subscribers`.	Use o número do projeto do Google Cloud no URL da solicitação, não o ID do projeto.
403 Proibido	O autor da chamada não tem permissão	Ao criar ou listar assinantes usando o ID do projeto do Google Cloud no URL da solicitação em vez do número do projeto. Isso se aplica a assinaturas de webhook usando o endpoint `projects.subscribers`.	Use o número do projeto do Google Cloud no URL da solicitação, não o ID do projeto.

Links universais e de apps

Avançar

Solução de problemas

Assinaturas de webhook Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Tipos de dados compatíveis

Contas de serviço do IAM

Configurar uma conta de serviço

Papéis do CPE

Gerenciar assinantes

Criar um assinante

Solicitação

Resposta

Listar assinantes

Solicitação

Resposta

Atualizar um assinante

Solicitação

Resposta

Excluir um assinante

Solicitação

Resposta

Verificação de endpoints

Rotação de chaves

Assinaturas do usuário

Assinaturas automáticas

Assinaturas manuais

Notificações

Formato da notificação

Responder a uma notificação

Verificação de assinatura

Como verificar a assinatura

Status e recuperação de assinantes

Erros comuns

Assinaturas de webhook