Best practices

This page is the short list of practices we recommend for every production integration.

Keep your IP allowlist current

Every API key is locked to the source IPs you gave us at provisioning. If your servers’ egress IPs change (cloud migration, new data center, fleet expansion), email us the new list before the cutover. If we don’t have the new IPs, your mint requests start returning 403 forbidden_ip and the integration goes dark. See IP allowlist.

Mint a fresh token per connection

Tokens are valid for 10 minutes. Mint one when you’re about to open a WebSocket; don’t mint ahead of time and hold tokens for later. If your connection drops and you reconnect, mint again.

Reconnect with backoff

When a connection drops, wait before reconnecting. Start at 1 second and double on consecutive failures (1s, 2s, 4s, 8s, 16s, 30s cap). Add 25% jitter. Reset to 1 second once any reconnect succeeds. See Reconnection.

Keep the connection alive

An idle connection drops after about 100 seconds. Either let your library send protocol-level pings automatically, or send a text "ping" every 30 seconds for clients that can’t. See Heartbeat.

Branch on type, ignore unknown fields

Every event has a stable type field. Branch on it; treat unknown event types as no-ops rather than errors. New fields may be added to existing event types over time; ignore fields you don’t recognize and they won’t break your handler.

Treat message strings as human-only

WebSocket error events carry a code and a message. The code is stable and safe to switch on; the message is for logs and humans only. Never parse message in your control flow.

Log connection events

Log every reconnect with the close code, the reason, and the timestamp. This is the single most useful piece of telemetry for diagnosing flaky connections; without it you have nothing to work from when contacting us.

Don’t share API keys across applications

Each application that connects should have its own API key, not a shared one. Each key has its own IP allowlist, so per-key keys let you scope the allowlist tightly to one service’s egress and rotate one key without disturbing the others. Contact us to provision additional keys.

Watch for privacy_changed with reason: "unavailable"

This is the only event that means we’ve stopped tracking a user. Update your UI to reflect lost access, and don’t expect more events for that user until a later privacy_changed with reason: "now_public" arrives. See Privacy changed.