Licensing Telemetry - Documentação do Evolution Foundation

What this page covers

This page describes the telemetry of the licensing system (activation + heartbeat) — what powers the instance count for the Evolution Foundation.

Exact payload — activation

Sent once, on POST /v1/activate:

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

Headers:

Content-Type: application/json
X-API-Key: <64-char hex api_key>
X-Signature: <HMAC-SHA256 of body>

Fields auto-extracted by the server (not sent explicitly):

Field	Source	Use
`operator_country`	GeoIP from request IP	Aggregated metrics by country
`operator_city`	GeoIP from request IP	Aggregated metrics by region
`server_ip`	`X-Forwarded-For` or `RemoteAddr`	Duplicate activation detection
`activated_at`	Server timestamp	Immutable log

Exact payload — heartbeat

Sent every 5 minutes, on POST /v1/heartbeat:

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

`telemetry_bundle` fields

The telemetry_bundle is a free-form JSON object. The server auto-extracts:

Field	Type	Meaning
`messages_sent`	number	Total messages sent since last heartbeat. Server adds to the global accumulator.
`features`	string[]	List of active features on the instance. E.g. `["chatbot", "broadcast", "webhook", "api-rest"]`

Any extra field included in the bundle is stored in the telemetry_bundles table for future inspection, but is not part of default processing.

What `features` can contain

Common values observed in production:

chatbot — integration with Chatwoot, Typebot, Dify, n8n, etc.
broadcast — bulk send
webhook — configured webhooks
api-rest — REST API usage
s3 / minio — object-storage media
rabbitmq / sqs / websocket — event transport
cloudapi — WhatsApp official Cloud API
crm — Evo CRM integration

The exact list depends on the product version.

What is NOT in the payload

These fields are never sent, in any version:

Message content
Conversation identifiers
End-user WhatsApp numbers
Media (images, audio, video)
Webhook tokens or third-party API keys
Instance environment variables
Chatbot configurations
Database credentials
Application logs
Stack traces or internal errors

The presence of any of these in a payload would be a critical violation of the telemetry policy and treated as a critical bug.

How to audit locally

You can intercept the traffic to confirm what is being sent.

With `mitmproxy`

# In one window
mitmproxy -p 8888

# In another, redirect the instance
export HTTPS_PROXY=http://localhost:8888
export LICENSE_BASE_URL=https://license.evolutionfoundation.com.br
# restart the instance

Each POST /v1/heartbeat shows up in mitmproxy with the full body, ready for inspection.

With tcpdump + jq

# Capture traffic to the licensing server
sudo tcpdump -i any -A -s 0 'host license.evolutionfoundation.com.br and port 443'

(TLS encrypts the content — to inspect JSON, use mitmproxy with a local CA installed.)

Inspecting locally in code

Evolution API exposes a debug endpoint that returns the last heartbeat sent:

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

Response:

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

The exact endpoint may vary by version. See the product changelog for details.

Frequency and cost

Operation	Frequency	Typical payload
`POST /v1/register/init`	Once per instance lifetime	~150 bytes
`GET /v1/register/status`	Poll every ~3–5s during registration	~50 bytes
`POST /v1/activate`	Once per service startup	~150 bytes
`POST /v1/heartbeat`	Every 5 min (≈ 288/day)	~250 bytes
`POST /v1/deactivate`	Graceful shutdown (optional)	~80 bytes

Estimated monthly traffic cost: < 3 MB per instance.

Data retention

Data type	Retention
`register/init` tokens	30 minutes (auto-expires)
`instance_id` + `api_key`	Indefinite while instance is active
Heartbeats	Last 90 days in hot table, aggregates kept indefinitely
Activation logs	12 months
Aggregated metrics (anonymized)	Indefinite

Compliance

LGPD (Brazil)

Email and phone are processed under legitimate interest for the operation of the open source project
Operators can request data deletion via [email protected]
No natural-person profiling
instance_id is a random UUID, not derived from PII

Collection is proportionate and necessary for the registration to work
Right to erasure preserved
DPO via [email protected]

Future changes

Any change to telemetry will be:

Announced in the product changelog
Documented on this page
Shipped as a release candidate before the stable release

If a new collected field is added, it will appear explicitly in the “Exact payload” section above.

Reporting inconsistencies

If you observe any field being sent outside what is documented on this page, report it as a security bug:

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

Undocumented telemetry issues are treated as high priority.

​What this page covers

​Exact payload — activation

​Exact payload — heartbeat

​telemetry_bundle fields

​What features can contain

​What is NOT in the payload

​How to audit locally

​With mitmproxy

​With tcpdump + jq

​Inspecting locally in code

​Frequency and cost

​Data retention

​Compliance

​LGPD (Brazil)

​GDPR (Europe)

​Future changes

​Reporting inconsistencies

What this page covers

Exact payload — activation

Exact payload — heartbeat

`telemetry_bundle` fields

What `features` can contain

What is NOT in the payload

How to audit locally

With `mitmproxy`

With tcpdump + jq

Inspecting locally in code

Frequency and cost

Data retention

Compliance

LGPD (Brazil)

GDPR (Europe)

Future changes

Reporting inconsistencies