Guides

REST API & webhooks

Collector OpenAPI spec, raw HTTP examples, auth models, and workspace REST roadmap.

AI brief: Live OpenAPI 3.1 at trackrift.com/openapi.json documents /collect, /s2s/collect, /bootstrap, /m, /v1/u.js. Workspace REST (leads, orders, outbound webhook subscriptions) is on the roadmap; use @trackrift/sdk for browser/server ingest today.

Trackrift exposes two API layers today: the collector (high-volume event ingest, documented in OpenAPI) and the dashboard app (configuration UI). Workspace REST for CRM-style integrations is shipping next.

Collector API (available now)

Endpoint	Auth	Purpose
POST /collect	public_id in payload + origin allowlist	Browser batch ingest
POST /s2s/collect	Bearer server ingest token	CRM, webhooks, Server Actions
GET /bootstrap	None (cookie Set-Cookie)	Issue / refresh anonymous session cookies
POST /m	Signed ?_uid= token	Magic-link identity merge
GET /v1/u.js	Query id=PUBLIC_ID	Universal script bootstrap loader

collect-batch.json

Minimal browser event shape (see OpenAPI for full schema)

{
  "public_id": "YOUR_PUBLIC_ID",
  "events": [{
    "event_name": "page_view",
    "event_id": "550e8400-e29b-41d4-a716-446655440000",
    "anonymous_id": "anon_…",
    "timestamp": "2026-05-26T12:00:00.000Z",
    "page": { "url": "https://example.com/pricing", "path": "/pricing" },
    "source": "web",
    "consent": { "analytics_storage": true, "ad_user_data": true }
  }]
}

Authentication models

Browser ingest trusts public_id (public, embeddable) plus optional allowed origins. This is intentional — the id identifies the workspace, not a secret. Sensitive operations use server tokens.

Server ingest requires a Bearer token with ingest scope. Rotate tokens in Settings → API keys. Never ship server tokens to the client bundle.

Rate limits

Collector endpoints apply per-workspace rate limits (return 429 with Retry-After). The SDK batches and backs off automatically; raw HTTP clients should implement exponential retry on 429/503.

Workspace REST (roadmap)

Planned resources: GET/POST /v1/leads, /v1/orders, attribution exports, and webhook subscription CRUD. Errors will follow RFC 7807 (application/problem+json) with stable type URIs on this domain.

Outbound webhooks (Trackrift → your app)

HMAC SHA-256 signed payloads via X-Trackrift-Signature, exponential retries (1m, 5m, 30m, 2h), and typed events such as order.attributed, lead.created. Verify signatures with your workspace webhook secret.

verify-webhook.ts

import { createHmac, timingSafeEqual } from 'crypto';

export function verifyTrackriftWebhook(
  rawBody: string,
  signatureHeader: string,
  secret: string,
): boolean {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
  const received = signatureHeader.replace(/^sha256=/, '');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}