API keys and webhook signatures

API access lets teams automate reporting while keeping each credential scoped to a workspace.

Create scoped keys

Use read-only keys for reporting jobs and read-write keys only for trusted automation that updates goals, funnels, or configuration.

Store API keys as secrets and rotate them when automation ownership changes. Every request should include the workspace context, and backend routes should reject keys that are expired, invalid, or attached to another workspace.

Call versioned endpoints

Use `/api/v1` routes for workspaces, tracked pages, reports, funnels, goals, exports, AI insights, and webhooks. Versioning in the path keeps client integrations predictable as the API evolves.

Verify webhook signatures

Every webhook delivery includes an HMAC signature. Compare the received signature with your computed digest before processing the payload.

The signature header uses the `sha256=` format. Compute the digest from the raw request body and the endpoint secret, then use a timing-safe comparison before acknowledging the event.

Monitor delivery retries

Failed deliveries are retried with backoff and disabled after repeated failures so noisy endpoints do not damage operational reliability.

Use the webhook delivery table to inspect response codes, response bodies, attempts, next retry time, and final status. Alert owners when endpoints fail repeatedly so they can fix downstream systems before data is missed.