How to send custom events on PostHog

First, install the PostHog SDK for your platform. For JavaScript/web applications, add the PostHog snippet to your HTML or install via npm:

npm install posthog-js

Initialize PostHog in your application with your project API key:

import posthog from 'posthog-js'

posthog.init('YOUR_API_KEY', {
  api_host: 'https://app.posthog.com'
})

Before sending events, plan your event naming convention and properties. Use descriptive names in snake_case format:

• Event name: describes the action (e.g., button_clicked, purchase_completed)
• Properties: additional context as key-value pairs
• User properties: attributes about the user performing the action

Example event structure:

{
  event: 'product_purchased',
  properties: {
    product_name: 'Premium Plan',
    price: 29.99,
    currency: 'USD'
  }
}

Use the posthog.capture() method to send your custom events. The basic syntax is:

posthog.capture('event_name', {
  property1: 'value1',
  property2: 'value2'
})

Real example for tracking a button click:

document.getElementById('signup-button').addEventListener('click', function() {
  posthog.capture('signup_button_clicked', {
    button_location: 'header',
    page_url: window.location.href,
    user_type: 'visitor'
  })
})

Identify users to connect events across sessions using posthog.identify():

posthog.identify('user_12345', {
  email: 'user@example.com',
  name: 'John Doe',
  plan: 'premium'
})

After identification, all subsequent events will be associated with this user. You can also set user properties separately:

posthog.people.set({
  subscription_status: 'active',
  last_login: new Date().toISOString()
})

Add custom events for important user actions throughout your application:

Form Submissions:

posthog.capture('form_submitted', {
  form_name: 'contact_form',
  form_fields: ['name', 'email', 'message']
})

Feature Usage:

posthog.capture('feature_used', {
  feature_name: 'advanced_search',
  search_query: searchTerm,
  results_count: resultsFound
})

Error Tracking:

posthog.capture('error_occurred', {
  error_type: 'validation_error',
  error_message: errorMsg,
  page_section: 'checkout'
})

Navigate to your PostHog dashboard and go to Events > Live Events to see your custom events in real-time. Verify that:

• Event names appear correctly
• Properties contain expected values
• User identification is working
• Timestamps are accurate

You can also check the Events tab to see aggregated event data and create insights. Use the search function to filter for your specific custom events by typing the event name in the search bar.

Create validation rules and monitoring for your custom events:

Add Event Validation:

function trackCustomEvent(eventName, properties) {
  if (!eventName || typeof eventName !== 'string') {
    console.error('Invalid event name');
    return;
  }
  
  posthog.capture(eventName, {
    ...properties,
    timestamp: new Date().toISOString(),
    source: 'web_app'
  });
}

Set up alerts in PostHog by going to Insights > create a trend for your custom event > click Alerts to monitor event volume changes.