Custom Events

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

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, etc.

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

Server-Side Events (API)

Send events from your backend without relying on the browser at all. Useful for purchase confirmations, webhook processing, or any server-triggered action.

curl -X POST https://your-hitkeep.example/ingest/event \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": "YOUR_SITE_ID",
    "name": "purchase",
    "url": "https://your-site.com/checkout/success",
    "referrer": "",
    "props": {
      "plan": "pro",
      "amount": "49"
    }
  }'

The url field should reflect the page where the event conceptually occurred. It is used for attribution in the dashboard.

Tracking Goals with Events

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

curl -X POST https://your-hitkeep.example/api/sites/{site_id}/goals \
  -H "Content-Type: application/json" \
  -b "hk_token=YOUR_SESSION_COOKIE" \
  -d '{"name":"Pro Signup","type":"event","value":"signup"}'

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

Dashboard Workflow

1. Emit events using either method above.
2. Open your site in the dashboard.
3. Navigate to Goals and create a new Event goal using the event name.
4. 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	HITKEEP_INGEST_RATE_LIMIT	20.0
-ingest-burst	HITKEEP_INGEST_BURST	40

See Configuration Reference for all options.

Related

• Goals
• Funnels
• Configuration Reference
• REST API Reference

Need event streaming or real-time webhooks on top of custom events? Join the HitKeep Cloud waitlist →