Custom events - Vibefollow

For events that aren’t part of the canonical lifecycle set, use events.track(). The name is accepted as-is — the backend validates only that it’s a non-empty string.

Single events

await vf.events.track('dashboard_created', 'usr_42', {
  source: 'wizard',
  workspaceId: 'ws_3',
});

The first argument is the event name. The second is the external user ID. The third is an optional properties bag — anything JSON-serialisable.

The 10 canonical lifecycle names work through track() as well, but prefer the typed helpers in vf.users.* for autocomplete and type safety.

Naming conventions

Event names: snake_case

Use dashboard_created, not DashboardCreated. Stable across audience filters and triggers.

Use stable identifiers, not labels

Renaming an event breaks any audience filter that already references the old name. Treat event names like database column names — pick once, live with it.

Properties: camelCase keys

Use workspaceId, not workspace_id. The backend normalises both to the same column, but consistency in your own code is worth holding the line on.

Batch tracking

For high-volume work — backfilling historical events, syncing from a data warehouse, replaying a Segment export — use events.batch() to amortise HTTP overhead:

const batch = vf.events.batch({ maxSize: 100, maxAgeMs: 5_000 });

for (const row of historicalEvents) {
  batch.track(row.name, row.userId, row.properties);
}

// Drain on shutdown.
await batch.flush();

The batch auto-flushes when:

The queue reaches maxSize events (default 100), or
maxAgeMs has elapsed since the first queued event (default 5000), or
You call flush() explicitly.

Always await batch.flush() before process exit. Lambda-style runtimes that freeze the event loop will lose any queue still in memory.

Trade-offs

	`events.track()`	`events.batch()`
Latency	Per-event POST	Buffered, drains in one POST
Failure mode	Single event fails	Full batch retried
Use when	Real-time interactive flow	Backfills, sync jobs, write-heavy paths

Batches are not idempotent across drains — if the POST fails midway through retries, the batch may be partially accepted server-side. Re-emit conservatively or set a retention-policy filter on your end to dedupe by event ID.

Reserved names

Reserved-name routing is an API-side concern, not the SDK’s. Custom names that happen to collide with a future reserved name will be rejected at validation with ValidationError — you’ll know immediately.

The current reserved set is the 10 canonical lifecycle names. Treat anything Vibefollow ships with as reserved.

​Single events

​Naming conventions

​Batch tracking

​Trade-offs

​Reserved names

Single events

Naming conventions

Batch tracking

Trade-offs

Reserved names