Telemetria de Licenciamento - Documentação do Evolution Foundation

O que esta página cobre

Esta página descreve a telemetria do sistema de licenciamento (ativação + heartbeat) — o que sustenta a contagem de instâncias da Evolution Foundation.

Payload exato — ativação

Enviado uma vez, no POST /v1/activate:

{
  "instance_id": "550e8400-e29b-41d4-a716-446655440000",
  "version": "2.4.0"
}

Headers:

Content-Type: application/json
X-API-Key: <api_key de 64 chars hex>
X-Signature: <HMAC-SHA256 do body>

Campos extraídos automaticamente pelo servidor (sem envio explícito):

Campo	Origem	Uso
`operator_country`	GeoIP do IP da request	Métricas agregadas por país
`operator_city`	GeoIP do IP da request	Métricas agregadas por região
`server_ip`	`X-Forwarded-For` ou `RemoteAddr`	Detecção de ativações duplicadas
`activated_at`	Timestamp do servidor	Log imutável

Payload exato — heartbeat

Enviado a cada 5 minutos, no POST /v1/heartbeat:

{
  "instance_id": "550e8400-e29b-41d4-a716-446655440000",
  "telemetry_bundle": {
    "messages_sent": 1500,
    "features": ["chatbot", "broadcast", "webhook"]
  }
}

Campos do `telemetry_bundle`

O telemetry_bundle é um objeto JSON livre. O servidor extrai automaticamente:

Campo	Tipo	Significado
`messages_sent`	number	Total de mensagens enviadas desde o último heartbeat. O servidor soma ao acumulado global.
`features`	string[]	Lista de features ativas na instância. Ex.: `["chatbot", "broadcast", "webhook", "api-rest"]`

Qualquer campo adicional incluído no bundle é armazenado na tabela telemetry_bundles para consulta futura, mas não há processamento padrão sobre ele.

O que `features` pode conter

Valores comuns observados em produção:

chatbot — integração com Chatwoot, Typebot, Dify, n8n, etc.
broadcast — envio em massa
webhook — webhooks configurados
api-rest — uso da REST API
s3 / minio — armazenamento de mídia em object storage
rabbitmq / sqs / websocket — eventos
cloudapi — Cloud API oficial do WhatsApp
crm — integração com Evo CRM

A lista exata depende da versão do produto.

O que NÃO está no payload

Estes campos nunca são enviados, em nenhuma versão:

Conteúdo de mensagens
Identificadores de conversas
Números de WhatsApp dos contatos
Mídia (imagens, áudios, vídeos)
Tokens de webhook ou API keys de terceiros
Variáveis de ambiente da instância
Configurações de chatbots
Credenciais de banco de dados
Logs da aplicação
Stack traces ou erros internos

A presença desses dados em qualquer payload seria uma violação grave da política de telemetria e seria tratada como bug crítico.

Como auditar localmente

Você pode interceptar o tráfego para confirmar o que está sendo enviado.

Com `mitmproxy`

# Em uma janela
mitmproxy -p 8888

# Em outra, redirecionar a instância
export HTTPS_PROXY=http://localhost:8888
export LICENSE_BASE_URL=https://license.evolutionfoundation.com.br
# reiniciar a instância

Cada POST /v1/heartbeat aparece no mitmproxy com body completo, pronto para inspeção.

Com tcpdump + jq

# Capturar tráfego para o licensing server
sudo tcpdump -i any -A -s 0 'host license.evolutionfoundation.com.br and port 443'

(TLS encripta o conteúdo — para inspecionar o JSON, use mitmproxy com CA local instalado.)

Inspecionando localmente no código

A Evolution API expõe um endpoint de debug que retorna o último heartbeat enviado:

GET /telemetry/last-heartbeat
Authorization: Bearer <admin_token>

Resposta:

{
  "sent_at": "2026-05-12T10:34:00Z",
  "body": {
    "instance_id": "...",
    "telemetry_bundle": {
      "messages_sent": 42,
      "features": ["chatbot"]
    }
  },
  "signature": "abc123..."
}

O endpoint exato pode variar por versão. Veja o changelog do produto para detalhes.

Frequência e custo

Operação	Frequência	Payload típico
`POST /v1/register/init`	1x na vida da instância	~150 bytes
`GET /v1/register/status`	polling de ~3–5s durante registro	~50 bytes
`POST /v1/activate`	1x por inicialização do serviço	~150 bytes
`POST /v1/heartbeat`	a cada 5 min (≈ 288/dia)	~250 bytes
`POST /v1/deactivate`	shutdown gracioso (opcional)	~80 bytes

Custo total mensal estimado em tráfego: < 3 MB por instância.

Retenção dos dados

Tipo de dado	Retenção
`register/init` tokens	30 minutos (expira automaticamente)
`instance_id` + `api_key`	Indefinida enquanto a instância estiver ativa
Heartbeats	Últimos 90 dias em tabela quente, agregados retidos indefinidamente
Logs de ativação	12 meses
Métricas agregadas (sem identificação)	Indefinidamente

Conformidade

LGPD (Brasil)

E-mail e telefone coletados são tratados sob base legal de legítimo interesse para operação do projeto open source
Operadores podem solicitar exclusão de dados via [email protected]
Não há perfilhamento de pessoa física
A instance_id é um UUID aleatório, não derivada de PII

A coleta é proporcional e necessária ao funcionamento do registro
Direito de exclusão preservado
DPO via [email protected]

Mudanças futuras

Qualquer mudança em telemetria será:

Anunciada no changelog do produto
Documentada nesta página
Disponibilizada em release candidate antes da release estável

Se for adicionada coleta de novo campo, ele aparecerá explicitamente na seção “Payload exato” acima.

Reportar inconsistência

Se você observar qualquer campo sendo enviado fora do documentado nesta página, reporte como bug de segurança:

E-mail: [email protected]
GitHub Security Advisory: evolution-api/security/advisories

Issues de telemetria não documentada são tratadas como prioridade alta.

​O que esta página cobre

​Payload exato — ativação

​Payload exato — heartbeat

​Campos do telemetry_bundle

​O que features pode conter

​O que NÃO está no payload

​Como auditar localmente

​Com mitmproxy

​Com tcpdump + jq

​Inspecionando localmente no código

​Frequência e custo

​Retenção dos dados

​Conformidade

​LGPD (Brasil)

​GDPR (Europa)

​Mudanças futuras

​Reportar inconsistência

O que esta página cobre

Payload exato — ativação

Payload exato — heartbeat

Campos do `telemetry_bundle`

O que `features` pode conter

O que NÃO está no payload

Como auditar localmente

Com `mitmproxy`

Com tcpdump + jq

Inspecionando localmente no código

Frequência e custo

Retenção dos dados

Conformidade

LGPD (Brasil)

GDPR (Europa)

Mudanças futuras

Reportar inconsistência