Como deixar meus usuários conectarem os dados de saúde deles com um QR code?

Mostre a cada usuário um QR code que traz o endereço do seu webhook e um segredo só daquele usuário. Ele escaneia o código com o app Life Dashboard, toca em Parear e, dali em diante, o celular dele envia os dados do Conexão Saúde (Health Connect), ou os do Apple Health em um iPhone, para o seu serviço em JSON assinado. Ninguém digita uma URL nem copia um segredo, e você sabe que deu certo porque o app envia na hora um ping de teste assinado. A integração Life Dashboard para o Home Assistant funciona exatamente assim, e o formato é aberto, então qualquer serviço pode fazer o mesmo.

Seu serviço mostra um QR code, o celular o abre na tela de pareamento e, depois de Parear, seu serviço recebe um ping de teste assinado

Por Owen Vogelaar, que mantém o Life Dashboard 5 min de leitura

Referência de pareamento

O que um código pode fazer

  • Preencher um endereço e o segredo dele. Nas seções que você permitir: Saúde, Tempo de tela ou as duas. O usuário ainda pode desativar uma seção na página de pareamento.
  • Nunca escolher tipos de dados nem uma agenda. Quais dados são enviados, e com que frequência, continua sendo escolha do usuário no celular. Um código não consegue começar a enviar a frequência cardíaca de alguém para algum lugar sem que a pessoa perceba.
  • Nunca mexer em outros receptores. Todos os outros endereços mantêm o próprio segredo e os próprios cabeçalhos, e um endereço adicionado por pareamento começa sem cabeçalhos personalizados.
  • Não salvar nada antes de Parear. A página de pareamento mostra o seu nome e o host para onde os dados vão, tirado do próprio endereço.

Um código é um link https com tudo depois do #:

https://owen282000.github.io/life-dashboard-companion-app/pair#v=1&url=<address>&secret=<secret>&name=<name>
CampoValor
v1, a versão do formato. Obrigatório.
urlO endereço do seu webhook, com no máximo 2048 caracteres, sem espaços e sem vírgula. Obrigatório.
secretO segredo de assinatura HMAC deste usuário, com no máximo 512 caracteres, sem espaços. Obrigatório.
nameComo a página de pareamento chama o seu serviço, com até 64 caracteres. Opcional.
sourceshealth_connect, screen_time ou os dois, separados por vírgula. Deixe de fora para aceitar os dois.

Aplique a codificação por porcentagem em cada valor por inteiro, com o espaço como %20. O quote(value, safe="") do Python e o encodeURIComponent do JavaScript fazem isso; a codificação de formulário, que escreve o espaço como +, não faz. O segredo fica no fragmento de propósito: um navegador nunca envia a um servidor a parte depois do #, então, quando alguém escaneia o código sem ter o app instalado, a página de destino carrega, mas o segredo continua no celular da pessoa.

Monte um código em Python

import secrets
from urllib.parse import quote, urlencode

import segno

PAIR_PAGE = "https://owen282000.github.io/life-dashboard-companion-app/pair"


def pairing_link(webhook_url, secret, name=None, sources=None):
    fields = {"v": "1", "url": webhook_url, "secret": secret}
    if name:
        fields["name"] = name
    if sources:
        fields["sources"] = ",".join(sources)
    return PAIR_PAGE + "#" + urlencode(fields, quote_via=quote, safe="")


secret = secrets.token_urlsafe(32)  # store this with the user
link = pairing_link("https://health.example.com/webhook/u/42", secret, name="Example Health")
segno.make(link, error="m").save("pairing.svg", scale=6, border=4)

Monte um código em Node.js

import crypto from "node:crypto";
import QRCode from "qrcode";

const PAIR_PAGE = "https://owen282000.github.io/life-dashboard-companion-app/pair";

function pairingLink(webhookUrl, secret, { name, sources } = {}) {
  const fields = [["v", "1"], ["url", webhookUrl], ["secret", secret]];
  if (name) fields.push(["name", name]);
  if (sources) fields.push(["sources", sources.join(",")]);
  return PAIR_PAGE + "#" + fields.map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join("&");
}

const secret = crypto.randomBytes(32).toString("base64url"); // store this with the user
const link = pairingLink("https://health.example.com/webhook/u/42", secret, { name: "Example Health" });
const dataUrl = await QRCode.toDataURL(link, { errorCorrectionLevel: "M", margin: 4 });

Os dois produzem exatamente o vetor de teste conhecido que os testes do próprio app conferem, e que está na referência de pareamento. Use-o como teste unitário do seu gerador.

O que o usuário vê

Ele escaneia o seu código no app, em Escanear um código de pareamento, ou com a câmera do celular, que no Android abre o app direto. Uma página diz “Example Health quer receber seus dados em health.example.com”, com uma chave para cada seção e os outros endereços, que mantêm o próprio segredo. Nada é salvo até ele tocar em Parear.

O ping de teste depois de Parear

Logo depois de Parear, o app envia um ping de teste para o seu endereço, assinado com o segredo do código:

POST /webhook/u/42
Content-Type: application/json; charset=utf-8
X-Signature: sha256=<hex of HMAC-SHA256(secret, raw body)>

{
  "test": true,
  "message": "Test ping from Life Dashboard",
  "timestamp": "2026-10-04T12:00:00Z",
  "app_version": "1.29.0",
  "source": "health_connect"
}

Confira a assinatura sobre o corpo bruto antes de interpretá-lo e responda com qualquer 2xx: o usuário vê “Conectado.” na página depois de Parear, ou uma mensagem curta que diz “ping de teste entregue” durante a configuração inicial do app. Responda 401 a uma assinatura errada, como em toda requisição depois dele. Um ping não traz dados, então é um bom momento para marcar o usuário como conectado, não algo para guardar. Toda sincronização depois dele usa o mesmo segredo e o mesmo payload, descrito no guia do webhook.

iPhone

O Life Dashboard para iPhone lê os mesmos códigos. Ele envia só o Apple Health, então um código precisa aceitar health_connect ou deixar sources de fora. O http:// sem criptografia só funciona ali para um endereço da rede de casa, então use https. A câmera do iPhone abre primeiro a página de destino, que passa o código para o app com um botão Open in the app.

Mantenha seguro

  • Um segredo por usuário, vindo de um gerador aleatório criptográfico, com pelo menos 32 bytes.
  • Mostre o código só para aquele usuário, depois que ele fizer login. Quem vê o código consegue assinar dados em nome dele.
  • Nunca registre o link em logs. Ele contém o segredo.
  • Deixe os usuários trocarem o segredo. Um segredo novo significa um código novo; ao escaneá-lo, o segredo antigo é substituído no celular.

Life Dashboard

Gere um código para um usuário de teste e escaneie com o app. A referência de pareamento traz todas as regras, o vetor de teste e as diferenças no iPhone.

Disponível no Google Play

€ 4,99 uma única vez no Google Play: o jeito fácil, com atualizações automáticas, e ainda apoia o desenvolvimento.

Ou de graça, o mesmo app com a mesma chave de assinatura: APK no GitHub · Obtainium · F‑Droid

Baixar na App Store

€ 6,99 uma única vez na App Store, sem assinatura.

Compilar com o Xcode

Referência de pareamento Referência do payload

Os apps de código aberto que este guia usa, para Android e iPhone. Sem conta e sem nuvem. Mais sobre o app para Android e para iPhone.

Perguntas frequentes

Meus usuários precisam de uma conta no Life Dashboard?

Não. Não existe servidor nem conta do Life Dashboard. O celular envia direto para o endereço que está no seu código.

Um código pode escolher quais dados de saúde o meu serviço recebe?

Não. Um código só preenche o endereço e o segredo. O usuário escolhe os tipos de dados e a agenda no celular, e assim o consentimento continua com ele.

Posso receber o payload no meu próprio formato?

Não. Todo receptor recebe o mesmo JSON assinado, descrito por um JSON Schema, e o seu serviço o converte para o próprio modelo. É ter um único formato documentado que permite a qualquer receptor funcionar sem plugin.

E se o usuário escanear sem ter o app instalado?

O link abre uma página que diz onde baixar o app, para Android ou iPhone. O segredo do link nunca chega ao servidor dessa página.