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) 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:

  • Etapas
  • Altitude
  • Distância
  • Andares
  • Peso
  • Sono

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
    • https://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_measurements
    • https://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.sleep
    • https://www.googleapis.com/auth/googlehealth.sleep.readonly

Gerenciar inscritos

Antes de receber notificações, você precisa 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 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 endpoint create. Você precisa fornecer:

  • 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 authorization_token que você fornece. O valor de authorization_token é 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 authorization_token como Bearer R4nd0m5tr1ng123 para autenticação de portador ou Basic dXNlcjpwYXNzd29yZA== para autenticação básica.
  • subscriberId: um identificador exclusivo que você fornece 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])).

Em subscriberConfigs, você precisa definir subscriptionCreatePolicy para cada tipo de dados. Defina como AUTOMATIC para usar assinaturas automáticas ou MANUAL se você pretende gerenciar as assinaturas do 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": {
    "authorization_token": "Bearer example-secret-token"
  }
}

Resposta

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

Listar assinantes

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

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 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 o formato camel case para nomes de 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",
  "state": "ACTIVE",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ],
  "endpointAuthorization": {
    "authorizationTokenSet": true
  }
}

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. O servidor precisa responder com um status 200 OK ou 201 Created.
  • Desafio não autorizado: a segunda solicitação é enviada sem credenciais. O 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:

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

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

Assinaturas do usuário

A API Google Health ajuda você a gerenciar as assinaturas do usuário de maneira eficiente, 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 do assinante automático 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 você preferir gerenciar as assinaturas de cada usuário manualmente, defina subscriptionCreatePolicy como MANUAL em subscriberConfigs. Com essa política, as assinaturas do usuário 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 o uso de assinaturas 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 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-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 os dados são removidos devido a um evento do sistema, como um usuário revogando a permissão ou excluindo a conta.

Recomendamos que você torne a lógica de processamento de notificações idempotente, especialmente para operações UPSERT, já que as novas tentativas podem fazer com que notificações duplicadas sejam enviadas.

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ê 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 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

O 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
    });
});

Status e recuperação do assinante

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.

Anterior
Links universais e de apps
Avançar
Solução de problemas