Documentation
API Reference
Event API

Event API

The Event API allows you to send events from your server to Overcentric. This is useful for tracking events that happen on the backend, such as subscription purchases, webhook events, or any action that doesn’t occur in the browser.

API Endpoint

Send events as a POST request to:

https://app.overcentric.com/api/v1/event

Request Format

The request body should be a JSON object with event and optional identity objects at the top level.

Headers 

Content-Type: application/json

Request Body 

{
  "event": {
    "name": "event_name",
    "properties": {
      "key": "value"
    },
    "project_id": "your-project-id",
    "device_id": "unique-device-id",
    "session_id": "current-session-id",
    "context": "product",
    "url": "https://app.example.com/page",
    "hostname": "app.example.com"
  },
  "identity": {
    "unique_identifier": "user_123",
    "email": "user@example.com",
    "name": "John Doe",
    "project_id": "your-project-id"
  }
}

Event Object Fields

Field Required Description
name Yes The event name. Use reserved names for pre-built reports.
properties No JSON object with custom data for the event
project_id Yes Your unique Project ID from the dashboard
device_id Yes Unique device identifier. Get from window.overcentricDeviceId on the client.
session_id Yes Current session identifier. Get from window.overcentricSessionId on the client.
context Yes Either "website" or "product"
url No The URL where the event occurred
hostname No The hostname of the page

Identity Object Fields

The identity object is optional but recommended for associating events with users.

Field Required Description
unique_identifier Yes (if identity included) Unique ID for the user
email No User’s email address
name No User’s name
project_id Yes (if identity included) Must match the event’s project_id

Getting Device and Session IDs

For a complete user journey, pass the device and session IDs from the browser to your backend:

// On the client side
const deviceId = window.overcentricDeviceId;
const sessionId = window.overcentricSessionId;

// Send these to your backend with your API request
fetch('/api/purchase', {
  method: 'POST',
  body: JSON.stringify({
    // ... your data
    overcentricDeviceId: deviceId,
    overcentricSessionId: sessionId
  })
});

Example: Subscription Purchase

This example tracks a subscription purchase from your backend:

cURL 

curl --location 'https://app.overcentric.com/api/v1/event' \
--header 'Content-Type: application/json' \
--data '{
  "event": {
    "name": "$subscription_purchase",
    "properties": {
      "plan": "premium",
      "price": 29.99,
      "interval": "monthly"
    },
    "project_id": "your-project-id",
    "device_id": "device-id-from-client",
    "session_id": "session-id-from-client",
    "context": "product",
    "url": "https://app.example.com/checkout/success",
    "hostname": "app.example.com"
  },
  "identity": {
    "unique_identifier": "user_123",
    "email": "user@example.com",
    "name": "John Doe",
    "project_id": "your-project-id"
  }
}'

Node.js 

const response = await fetch('https://app.overcentric.com/api/v1/event', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    event: {
      name: '$subscription_purchase',
      properties: {
        plan: 'premium',
        price: 29.99,
        interval: 'monthly'
      },
      project_id: 'your-project-id',
      device_id: deviceIdFromClient,
      session_id: sessionIdFromClient,
      context: 'product',
      url: 'https://app.example.com/checkout/success',
      hostname: 'app.example.com'
    },
    identity: {
      unique_identifier: 'user_123',
      email: 'user@example.com',
      name: 'John Doe',
      project_id: 'your-project-id'
    }
  })
});

Python 

import requests

response = requests.post(
    'https://app.overcentric.com/api/v1/event',
    json={
        'event': {
            'name': '$subscription_purchase',
            'properties': {
                'plan': 'premium',
                'price': 29.99,
                'interval': 'monthly'
            },
            'project_id': 'your-project-id',
            'device_id': device_id_from_client,
            'session_id': session_id_from_client,
            'context': 'product',
            'url': 'https://app.example.com/checkout/success',
            'hostname': 'app.example.com'
        },
        'identity': {
            'unique_identifier': 'user_123',
            'email': 'user@example.com',
            'name': 'John Doe',
            'project_id': 'your-project-id'
        }
    }
)

Use Cases

Webhook Events

Track events from payment providers like Stripe:

// In your Stripe webhook handler
app.post('/webhooks/stripe', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'customer.subscription.created') {
    await fetch('https://app.overcentric.com/api/v1/event', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        event: {
          name: '$subscription_purchase',
          properties: {
            plan: event.data.object.plan.id,
            amount: event.data.object.plan.amount / 100
          },
          project_id: 'your-project-id',
          device_id: 'webhook',
          session_id: 'webhook',
          context: 'product'
        },
        identity: {
          unique_identifier: event.data.object.customer,
          project_id: 'your-project-id'
        }
      })
    });
  }
  
  res.sendStatus(200);
});

Backend Actions

Track actions that happen entirely on the server:

  • Email sends
  • Background job completions
  • Admin actions
  • Scheduled tasks