Send server-side events

Track events from your backend services using the Vision API. This is useful for recording actions that happen outside the browser, such as webhook events, payment completions, or background job results.

When to use server-side tracking

  • Payment webhooks: Record purchases confirmed by Stripe, PayPal, or other payment processors.
  • API actions: Track when users perform actions through your API (e.g., mobile app events).
  • Background jobs: Record events from cron jobs, email sends, or data processing pipelines.
  • Importing historical data: Backfill events from another analytics platform.

Using the Node client

The simplest approach for Node.js backends is the Vision Node client:

npm install @vision/node
import Vision from "@vision/node";

Vision.init({
  projectId: "your-project-id",
  hostUrl: process.env.NEXT_PUBLIC_API_URL,
});

// Track a page view
await Vision.track({ url: "/api/checkout", title: "Checkout API" });

// Track a custom event
await Vision.track({
  name: "payment-received",
  data: {
    revenue: 49.99,
    currency: "USD",
    plan: "pro",
  },
});

Using the API directly

Send a POST request to /send with the event payload:

curl -X POST NEXT_PUBLIC_API_URL/send \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Server)" \
  -d '{
    "payload": {
      "hostname": "example.com",
      "language": "en-US",
      "url": "/checkout",
      "project": "your-project-id",
      "name": "payment-received",
      "data": {
        "revenue": 49.99,
        "currency": "USD"
      }
    },
    "type": "event"
  }'

Important: A valid User-Agent header is required. Requests without one will be rejected.

Python example

import os
import requests

api_url = os.environ.get("NEXT_PUBLIC_API_URL", "https://api.yourdomain.com")

requests.post(f"{api_url}/send", json={
    'payload': {
        'hostname': 'example.com',
        'language': 'en-US',
        'url': '/checkout',
        'project': 'your-project-id',
        'name': 'payment-received',
        'data': {
            'revenue': 49.99,
            'currency': 'USD',
        },
    },
    'type': 'event',
}, headers={
    'User-Agent': 'MyApp/1.0',
})

Batch sending

To send multiple events in a single request, POST a JSON array to the /batch endpoint. Each element of the array has the same shape as an /send request body:

curl -X POST NEXT_PUBLIC_API_URL/batch \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Server)" \
  -d '[
    {
      "type": "event",
      "payload": {
        "project": "your-project-id",
        "hostname": "example.com",
        "url": "/page-1",
        "name": "page-view"
      }
    },
    {
      "type": "event",
      "payload": {
        "project": "your-project-id",
        "hostname": "example.com",
        "url": "/page-2",
        "name": "page-view"
      }
    }
  ]'

Each item uses the same schema as NEXT_PUBLIC_API_URL/send, supporting identical type values (event, identify, performance) and payload fields. The response summarizes the batch:

{
  "size": 2,
  "processed": 2,
  "errors": 0,
  "details": [],
  "cache": "..."
}

If any items fail, errors is the failure count and details lists each failure by its index in the array.

Tips

  • Server-side events appear in the same dashboard as client-side events. Use event names or properties to distinguish them if needed.
  • When tracking revenue from payment webhooks, use the revenue and currency properties so data appears in the Payment insight.
  • For high-volume backends, consider queuing events and sending them with concurrency limits to avoid overwhelming your instance.