Event API | Overcentric Documentation

Documentation

API Reference

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/events

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`	No	Unique device identifier. Pass the browser’s value to tie a server event to the same visitor — see below.
`session_id`	No	Current session identifier. Same idea as `device_id`.
`context`	Yes	`"website"`, `"product"`, or `"mobile"`
`url`	No	The URL where the event occurred. Required for `website` and `product`; leave it out for `mobile`, which has no URL.
`hostname`	No	The hostname of the page. For `mobile`, send the app’s bundle identifier instead.

Sending mobile events yourself? Most apps should use the React Native SDK, which handles queueing, retries, and device metadata. Use this API directly only for server-side events.

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;

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

The session ID is not exposed on window. It lives in a cookie named overcentric_session_id_<your-project-id>, which your server can read from the incoming request if you want to attach it. Omitting session_id is fine — the event is still recorded and still attributed to the user through identity.

Example: Subscription Purchase

This example tracks a subscription purchase from your backend:

cURL

curl --location 'https://app.overcentric.com/api/events' \
--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/events', {
  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/events',
    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/events', {
      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