Custom Events

Your tracking script captures page views automatically, but you need to measure specific interactions: a purchase, a video play, a form submission. HitKeep’s custom event API lets you record any named action from the browser or from your server.

If you only need baseline browser interactions such as outbound links, file downloads, or form submits, start with Automatic Events. The default tracker already emits outbound_click, file_download, and form_submit without manual window.hk.event() calls.

For how hk.js sends payloads, retries failed delivery, handles SPA navigation, and limits browser storage, see Tracker Architecture.

Event naming examples

Use specific event names that describe the business action. Keep properties small, structured, and free of secrets, raw prompts, form field values, and access tokens.

Workflow	Example event names	Typical path
Signup	`signup_started`, `signup_completed`	Browser or server-side event
Leads	`demo_requested`, `contact_form_submitted`	Browser or server-side event
Downloads	`whitepaper_downloaded`, `release_downloaded`	Browser event when automatic `file_download` is not specific enough
Ecommerce	`view_item`, `add_to_cart`, `begin_checkout`, `purchase`	Browser or server-side event
Assistants	`assistant.chat_started`, `assistant.message_sent`, `assistant.goal_assisted`	Browser or server-side event

For canonical event, export, storage, and runtime facts, see Facts and Limits.

Client-Side Events (Browser)

The hk.js tracking snippet exposes window.hk.event():

<script>
  // Record a named event with optional properties
  window.hk?.event?.('signup', { plan: 'pro' });
</script>

Call this anywhere in your page JavaScript: button click handlers, form submit callbacks, pricing interactions, onboarding steps, or other product-specific actions.

<button onclick="window.hk?.event?.('cta_clicked', { location: 'hero' })">
  Get Started
</button>

Server-Side Events (API)

Send events from your backend when the server confirms the action or when you need to preserve a historical timestamp. Common examples include purchase confirmations, webhook processing, trial starts, account upgrades, and replayed events from logs.

Use the trusted server-side event API with an API client token:

The url field should reflect the page where the event conceptually occurred. HitKeep uses it for site resolution and session context.

Tracking Goals with Events

Events become useful when combined with Goals. Create an event-based goal to count conversions:

API reference:

Create a goal

The goal value must match the event name exactly. Once created, the dashboard shows conversion counts and timeseries data for that event.

Recommended schema for AI chatbots

If you are instrumenting an on-site chatbot, keep the event names predictable so the dedicated AI chatbot dashboard can aggregate them automatically.

Recommended event names:

assistant.chat_started
assistant.message_sent
assistant.response_rendered
assistant.citation_clicked
assistant.handoff_requested
assistant.goal_assisted

Recommended properties include:

bot_id, provider, model, surface
conversation_id, message_index, intent
response_ms, tool_count, citation_count
goal_name, goal_value

Use structured metadata rather than raw prompt bodies whenever possible. That keeps storage leaner and avoids collecting sensitive conversation text by default.

For a complete walkthrough, see AI Chatbot Analytics.

Dashboard Workflow

Emit events using either method above.
Open your site in the dashboard.
Navigate to Goals and create a new Event goal using the event name.
The goal will appear in KPIs, charts, and the Goals timeseries.

Rate Limiting

Custom events share the ingest endpoint’s rate limiter. The default is 20 requests/sec per IP with a burst of 40. Adjust via configuration if sending high-volume server-side events from a single IP:

Flag	Env Variable	Default
`--ingest-rate-limit`	`HITKEEP_INGEST_RATE_LIMIT`	`20.0`
`--ingest-burst`	`HITKEEP_INGEST_BURST`	`40`

See Configuration Reference for all options.

Need event streaming or real-time webhooks on top of custom events? Start with HitKeep Cloud →