---
title: "Custom Event Tracking in HitKeep | HitKeep"
description: "Track server-side and client-side custom events in HitKeep. Use the ingest API to record button clicks, form submissions, purchases, and any other named action."
canonical: "https://hitkeep.com/guides/tracking/custom-events/"
---

# Custom Event Tracking in HitKeep

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](https://hitkeep.com/guides/tracking/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](https://hitkeep.com/guides/tracking/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](https://hitkeep.com/reference/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.

In React, Vue, Angular, or Astro projects, the typed [`@hitkeep/tracker` npm package](https://hitkeep.com/guides/tracking/npm-package/) exposes the same event API as an importable, compiler-checked `track()` function.

```
<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:

- [Server-Side Tracking](https://hitkeep.com/guides/tracking/server-side-tracking/)
- [Ingest server-side event](https://hitkeep.com/api/#tag/ingest/POST/api/ingest/server/event)

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](https://hitkeep.com/api/#tag/goals/POST/api/sites/%7Bid%7D/goals)

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](https://hitkeep.com/guides/analytics/ai-chatbot-analytics/).

## Dashboard Workflow

1. Emit events using either method above.
2. Open your site in the dashboard.
3. Navigate to **Events** to inspect event counts, property breakdowns, and audience panels for pages, sources, devices, countries, city, provider, and ASN context.
4. Navigate to **Goals** and create a new **Event goal** using the event name.
5. The goal will appear in KPIs, charts, and the Goals timeseries.

City, provider, and ASN are derived from transient IP metadata. They are not custom event properties, and HitKeep does not store raw visitor IP addresses with the event.

## 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](https://hitkeep.com/reference/configuration/) for all options.

## Related

- [Automatic Events](https://hitkeep.com/guides/tracking/automatic-events/)
- [Server-Side Tracking](https://hitkeep.com/guides/tracking/server-side-tracking/)
- [Cookieless Event Tracking](https://hitkeep.com/use-cases/cookieless-event-tracking/)
- [Tracker Architecture](https://hitkeep.com/guides/tracking/tracker-architecture/)
- [Facts and Limits](https://hitkeep.com/reference/facts-and-limits/)
- [Goals](https://hitkeep.com/guides/analytics/goals/)
- [Funnels](https://hitkeep.com/guides/analytics/funnels/)
- [Ecommerce Analytics](https://hitkeep.com/guides/analytics/ecommerce/)
- [AI Chatbot Analytics](https://hitkeep.com/guides/analytics/ai-chatbot-analytics/)
- [Configuration Reference](https://hitkeep.com/reference/configuration/)
- [REST API Reference](https://hitkeep.com/api/)

Need event streaming or real-time webhooks on top of custom events? [Start with HitKeep Cloud →](https://cloud.hitkeep.eu/signup?plan=free&billing=monthly&utm_source=hitkeep_docs&utm_medium=referral&utm_campaign=cloud_signup&utm_content=docs_inline)

[Previous Automatic events](https://hitkeep.com/guides/tracking/automatic-events/)[Next Server-side tracking](https://hitkeep.com/guides/tracking/server-side-tracking/)