Documentation · Trakvo

Quickstart

You're a few minutes away from having events flowing into Meta CAPI, TikTok Events API, and Google Ads. Trakvo runs server-side — it doesn't rely on third-party cookies and isn't blocked by AdBlock.

In 3 steps

1. Paste the snippet into your site's <head> (or install the Shopify app).
2. Connect your pixels in the dashboard via OAuth (Meta, TikTok, Google).
3. Fire events via POST /v1/events or let the snippet detect them automatically.

Universal snippet

Paste before </head>. Works on any store or custom landing page:

<!-- Trakvo -->
<script src="https://cdn.trakvo.co/t.js" data-site="YOUR_SITE_ID" async></script>

Where to find YOUR_SITE_ID? In the dashboard under Settings → Site ID. It's a unique 12-character identifier like trv_a7f4....

Core concepts

Three concepts to understand before diving in:

Shared Event ID

Every event has a unique event_id. The client-side snippet and the server-side dispatch use the same ID. The destination platform deduplicates on receipt — no double counting.

First-party data

Trakvo collects data on your domain (first-party), not on Trakvo's domain. This avoids blocks from iOS, AdBlock, and Safari ITP.

PII hashing

Email, phone, and personal identifiers are hashed via SHA-256 before transmission. The cleartext data never leaves Trakvo's database. LGPD and GDPR compliant.

Match Quality

Match Quality is the score (0-10) Meta assigns to the quality of the events you send. The more enriched PII fields, the better the AI matching and the lower your CPA.

Trakvo enriches automatically:

fbp and fbc (Facebook click cookies)
email and phone (SHA-256 hash)
external_id (internal customer ID, hashed)
fn / ln / city / state / zip / country (when available)
ip and user_agent (captured server-side)

Pro customers and above have guaranteed Match Quality 9.4+. If the score drops, the dashboard alerts you and our team investigates.

Integrations — Shopify

1-click install. Standard events (PageView, ViewContent, AddToCart, InitiateCheckout, Purchase) detected automatically.

How to install

Open apps.shopify.com/trakvo.
Click Install and authorize.
In the Trakvo dashboard, connect your Meta/TikTok/Google pixels.
Done — events start flowing in < 2 minutes.

Integrations — WooCommerce

Official plugin via the WordPress repository. Configuration via guided wizard.

# Via WP-CLI
wp plugin install trakvo --activate

Or download the ZIP from downloads.trakvo.co/wp-plugin and install via the WordPress admin interface.

Integrations — Hotmart and Kiwify

Integration via native webhook. Trakvo exposes a ready-made endpoint that receives Hotmart/Kiwify webhooks and automatically maps them to CAPI events.

Configure webhook

Copy your unique URL under Settings → Integrations → Hotmart.
Paste it into the Hotmart dashboard at Settings → Webhooks → Add.
Select events: Purchase Approved, Refunded, Chargeback.

Integrations — Cartpanda and Cakto

Same pattern: a unique webhook URL generated in the dashboard. Paste it into your checkout and conversion events arrive mapped to CAPI.

Integrations — Custom site

For your own store or a custom landing page, use the universal snippet + explicit JavaScript calls.

// Fire Purchase event manually
window.trakvo("Purchase", {
  value: 99.90,
  currency: "BRL",
  order_id: "ORD-12345",
  email: "[email protected]"  // hashed automatically
});

Integrations — Server-to-server

If you already have your own backend (Node, Ruby, Python, Go, .NET), fire events directly via the REST API. No client-side snippet needed.

curl -X POST https://{your-region}.api.trakvo.co/events \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Purchase",
    "value": 99.90,
    "currency": "BRL",
    "user": { "email_sha256": "..." }
  }'

API — Authentication

Every API request requires the header Authorization: Bearer YOUR_TOKEN. Generate tokens under Settings → API → Tokens.

Best practices

Tokens are per environment: generate separate ones for production, staging, and dev.
Never expose tokens in client-side code or Git commits.
Rotation: rotate tokens every 90 days as internal policy.

API — POST /v1/events

POST/v1/events

Fires a conversion event to be distributed to the connected pixels.

Body

Field	Type	Required	Description
`event`	string	yes	Event name (e.g., `Purchase`, `Lead`)
`event_id`	string	no	Unique ID for dedupe (auto-generated if omitted)
`value`	number	cond.	Monetary value (required for Purchase)
`currency`	string	cond.	ISO 4217 (BRL, USD, EUR)
`user`	object	yes	User identity (email, phone, ip, etc.)
`destinations`	array	no	Which pixels to fire (default: all)

Response

{
  "event_id": "evt_a7f4b2c9...",
  "status": "queued",
  "latency_ms": 142,
  "match_quality": 9.4,
  "destinations": [
    { "id": "meta", "status": "sent", "http": 200 },
    { "id": "tiktok", "status": "sent", "http": 200 }
  ]
}

API — GET /v1/events/:id

GET/v1/events/:id

Look up the delivery status of a specific event. Useful for debugging.

API — Rate limits

Plan	Requests/s	Burst
Starter	50	100
Pro	500	1,000
Business	Custom	Custom

When exceeded, the API responds 429 Too Many Requests with a Retry-After header.

API — Error codes

Status	Meaning	Action
`200`	Accepted and queued	—
`400`	Invalid payload	Check required fields
`401`	Invalid token	Generate a new token
`429`	Rate limit	Wait for `Retry-After`
`500`	Internal error	Retry with exponential backoff

SDK — JavaScript

# Install via npm
npm install @trakvo/js

import { Trakvo } from "@trakvo/js";

const trakvo = new Trakvo({ token: process.env.TRAKVO_TOKEN });

await trakvo.track("Purchase", {
  value: 99.90,
  currency: "BRL",
  user: { email: "[email protected]" }
});

SDK — PHP

# Install via composer
composer require trakvo/php

use Trakvo\Client;

$trakvo = new Client($_ENV['TRAKVO_TOKEN']);

$trakvo->track('Purchase', [
  'value'     => 99.90,
  'currency'  => 'BRL',
  'user'      => ['email' => '[email protected]'],
]);

Webhooks — Setup

Configure webhook URLs under Settings → Webhooks. Trakvo notifies your server when:

An event was delivered successfully.
An event failed after exhausting retries.
Match Quality drops below the configured threshold.
A pixel disconnects (OAuth token expired).

Webhooks — Validate HMAC

Every webhook request includes an X-Trakvo-Signature header. Validate it with HMAC-SHA256 + your webhook secret.

const crypto = require("crypto");

function validate(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(expected, signature);
}

Webhooks — Retry policy

If your endpoint responds with anything other than 2xx, Trakvo retries with exponential backoff:

Attempt 1: immediate
Attempt 2: 1 second
Attempt 3: 5 seconds
Attempt 4: 15 seconds
Attempt 5: 60 seconds

After 5 unsuccessful attempts, the event goes to the dead-letter queue — inspectable in the dashboard under Webhooks → Failures.

Resources — Event Catalog

Standard events supported natively (automatically mapped to each platform):

Event	Meta	TikTok	Google
`PageView`	PageView	Pageview	page_view
`ViewContent`	ViewContent	ViewContent	view_item
`AddToCart`	AddToCart	AddToCart	add_to_cart
`InitiateCheckout`	InitiateCheckout	InitiateCheckout	begin_checkout
`AddPaymentInfo`	AddPaymentInfo	AddPaymentInfo	add_payment_info
`Purchase`	Purchase	CompletePayment	purchase
`Lead`	Lead	SubmitForm	generate_lead
`Subscribe`	Subscribe	Subscribe	—

Resources — LGPD and consent

Every event accepts a consent field with the user's consent flag. Trakvo respects it end-to-end:

trakvo.track("Purchase", {
  value: 99.90,
  consent: {
    marketing: true,
    analytics: true,
    timestamp: "2026-05-24T15:00:00Z"
  }
});

Resources — Pixel Warmup

A new pixel doesn't optimize well — it lacks the event history the platform AIs need to learn. Pixel Warmup sends real events from other pixels belonging to the same customer, with temporal jitter, to give the new pixel an initial history.

Available on the Pro plan (up to 500 events/day) and Business (custom volume).

Important: only real events are reused — never synthetic ones. Match Quality is preserved. Volume is controlled to avoid being flagged as an anomaly.

Changelog

Public release history. RSS available at changelog.trakvo.co/rss.

v0.5 — In development

Native Shopify app (1-click install)
Advanced Pixel Warmup with scheduling
PHP SDK v2 with batch support

v0.4 — Private beta

Server-side CAPI for Meta, TikTok, Google
Real-time event dashboard (SSE)
Webhooks with HMAC + idempotency

Got questions?

Talk to us →

Security and compliance →

Everything you need to integratein under an hour

Quickstart

In 3 steps

Universal snippet

Core concepts

Shared Event ID

First-party data

PII hashing

Match Quality

Integrations — Shopify

How to install

Integrations — WooCommerce

Integrations — Hotmart and Kiwify

Configure webhook

Integrations — Cartpanda and Cakto

Integrations — Custom site

Integrations — Server-to-server

API — Authentication

Best practices

API — POST /v1/events

Body

Response

API — GET /v1/events/:id

API — Rate limits

API — Error codes

SDK — JavaScript

SDK — PHP

Webhooks — Setup

Webhooks — Validate HMAC

Webhooks — Retry policy

Resources — Event Catalog

Resources — LGPD and consent

Resources — Pixel Warmup

Changelog

v0.5 — In development

v0.4 — Private beta

Everything you need to integrate
in under an hour