Sending events through HTTP endpoint

The Usermaven has API for direct event collection. You can use it for sending events directly from apps or backends, including historical events.

1. Obtaining server token

Log in to your Usermaven account and select your workspace. After that go to the Workspace Settings > Setup. Select Python SDK and there you will find the Server Token.

2. Sending events

To send the event to Usermaven, you will have to send the request to the following endpoint.


 https://events.usermaven.com/api/v1/s2s/event?token=API_KEY.SERVER_TOKEN

Server Token Configuration

The API_KEY.SERVER_TOKEN is constructed by combining:

API Key
Server Token

Both values can be found in: Workspace Settings > General > Server side tracking credentials

Event body

The body is JSON object.


{
  "api_key": "API_KEY", // change this with your API key
  "event_id": "",
  "event_type": "user_identify", // once the user signs in to the platform.
  "_timestamp": 1632150122000,
  // Optional: UTC timestamp in milliseconds for historical events
  "ids": {},
  "user": {
    // Required attributes
    "anonymous_id": "random_id", // Ideally, use the __eventn_id from the cookies to stitch the user activity.
    "id": "lzL24K3kYw", // Unique ID for the user in database.
    "email": "user@domain.com", // Email address for the user.
    "created_at": "2021-01-20T09:55:35", // DateTime string in your system that represents when the user first signed up.
 
    // Recommended attributes
    // First name and last name are shown on people pages.
    "first_name": "John",
    "last_name": "Smith",
    // Optional attributes (you can name attributes what you wish)
    "custom": {
      "plan_name": "premium"
    }
  },
  // Send company level attributes
  "company": {
    "id": "65f02acc-e104-45d9-8199-1491332d8454",
    "name": "azhar",
    "created_at": "2022-02-15T17:25:08",
    "custom": {
      "plan": "premium"
    }
  },
  "screen_resolution": "0",
  "src": "http"
  "url": "http://localhost:3000/example",
  "page_title": "Your Page Title",
  "doc_path": "/example",
  "doc_host": "localhost",
  "doc_search": "",
  "vp_size": "0",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:127.0) Gecko/20100101 Firefox/127.0",
  "user_language": "en-US",
  "doc_encoding": "UTF-8"
}

Note: user_identify event type is required for the signed in users. Based on the user_identify event, your users will be available in our People view. Response


{ "status": "ok" }

Sending historical events

To send historical events, include the _timestamp field in your event payload. The _timestamp should be a UTC timestamp in milliseconds. This allows you to import past events with their original occurrence time.

Sending custom event attributes

If you would like to send the custom event, the only thing that is going to be changed from the above payload is event_type. For sending additional custom event attributes, you can pass the attributes in the form of event_attributes object.

Example payload


{
  "api_key": "API_KEY", // change this with your API key
  "_timestamp": 1632150122000, // Optional: UTC timestamp in milliseconds for historical events
  "event_id": "",
  "event_type": "plan_upgraded", // once the user signs in to the platform.
  // You can send event attributes as well.
  "event_attributes": {
    "amount": 100,
    "currency": "USD"
  },
  "ids": {},
  "user": {
    // Required attributes
    "anonymous_id": "random_id", // Ideally, use the __eventn_id from the cookies to stitch the user activity.
    "id": "lzL24K3kYw", // Unique ID for the user in database.
    "email": "user@domain.com", // Email address for the user.
    "created_at": "2021-01-20T09:55:35", // DateTime string in your system that represents when the user first signed up.
 
    // Recommended attributes
    // First name and last name are shown on people pages.
    "first_name": "John",
    "last_name": "Smith",
    // Optional attributes (you can name attributes what you wish)
    "custom": {
      "plan_name": "premium"
    }
  },
  // Send company level attributes
  "company": {
    "id": "65f02acc-e104-45d9-8199-1491332d8454",
    "name": "azhar",
    "created_at": "2022-02-15T17:25:08",
    "custom": {
      "plan": "premium"
    }
  },
  "screen_resolution": "0",
  "src": "http"
  "url": "http://localhost:3000/example",
  "page_title": "Your Page Title",
  "doc_path": "/example",
  "doc_host": "localhost",
  "doc_search": "",
  "vp_size": "0",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:127.0) Gecko/20100101 Firefox/127.0",
  "user_language": "en-US",
  "doc_encoding": "UTF-8"
}

Response


{ "status": "ok" }

3. Bulk events

The events API also support bulk events. In case if you would like to send multiple events in a single request, you can use the following payload.

Example


 
[
  {
    "api_key":  "API_KEY", // change this with your API key
    "event_id":  "",
    "event_type":  "plan_upgraded", // once the user signs in to the platform.
    "_timestamp":  1632150122000, // Optional: UTC timestamp in milliseconds for historical events
    // You can send event attributes as well.
    "event_attributes": {
      "amount":  100,
      "currency":  "USD"
    },
    "ids": {},
    "user": {
      // Required attributes
      "anonymous_id":  "random_id" , // Ideally, use the __eventn_id from the cookies to stitch the user activity.
      "id":  "lzL24K3kYw", // Unique ID for the user in database.
      "email":  "user@domain.com", // Email address for the user.
      "created_at":  "2021-01-20T09:55:35", // DateTime string in your system that represents when the user first signed up.
 
      // Recommended attributes
      // First name and last name are shown on people pages.
      "first_name":  "John",
      "last_name":  "Smith",
      // Optional attributes (you can name attributes what you wish)
      "custom": {
        "plan_name":  "premium",
      },
    },
 
    // Send company level attributes
    "company": {
      "id":  "65f02acc-e104-45d9-8199-1491332d8454",
      "name":  "azhar",
      "created_at":  "2022-02-15T17:25:08",
      "custom": {
        "plan":  "premium"
      }
    },
 
    "screen_resolution":  "0",
    "src":  "http"
  },
  {
 
    "api_key":  "API_KEY", // change this with your API key
    "event_id":  "",
    "event_type":  "plan_upgraded", // once the user signs in to the platform.
    "_timestamp":  1632150123000, // Optional: UTC timestamp in milliseconds for historical events
    // You can send event attributes as well.
    "event_attributes": {
      "amount":  25,
      "currency":  "USD"
    },
 
    "ids": {},
    "user": {
      // Required attributes
      "anonymous_id":  "random_id" , // Ideally, use the __eventn_id from the cookies to stitch the user activity.
      "id":  "lzL24K3kYw", // Unique ID for the user in database.
      "email":  "user@domain.com", // Email address for the user.
      "created_at":  "2021-01-20T09:55:35", // DateTime string in your system that represents when the user first signed up.
 
      // Recommended attributes
      // First name and last name are shown on people pages.
      "first_name":  "John",
      "last_name":  "Smith",
      // Optional attributes (you can name attributes what you wish)
      "custom": {
        "plan_name":  "premium",
      },
    },
    // Send company level attributes
    "company": {
      "id":  "65f02acc-e104-45d9-8199-1491332d8454",
      "name":  "azhar",
      "created_at":  "2022-02-15T17:25:08",
      "custom": {
        "plan":  "premium"
      }
    },
    "screen_resolution":  "0",
    "src":  "http"
    "url":"http://localhost:3000/example",
    "page_title":"Your Page Title",
    "doc_path":"/example",
    "doc_host":"localhost",
    "doc_search":"",
    "vp_size":"0",
    "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:127.0) Gecko/20100101 Firefox/127.0",
    "user_language":"en-US",
    "doc_encoding":"UTF-8"
  }
]

Response


{ "status": "ok" }

4. Sending high-quality server-side events

To ensure your server-side events are valuable and accurately attributed in Usermaven, it’s important to include essential metadata and structure your payloads clearly.

Key layers of a good server-side event

Envelope
Include your api_key and optionally a _timestamp (for historical backfill).
User & Company block
Always include the user’s permanent ID. If the user isn’t identified yet, provide an anonymous_id to associate early activity. Add useful user traits (like email, name, signup date), and optionally, company details if it’s a B2B context.
Event block
Describe what happened using event_type and optionally attach any event_attributes that help analyze the event (like amount, status, method, etc.).
Context block
Add context to improve accuracy and enrich analytics:
- ip: User’s IP address.
- userAgent: Browser/device string.
- page: Include url, referrer, title, and path if available.
- campaign: UTM parameters like source, medium, campaign, term, and content.
- library: Info about what system sent the event (e.g., service name and version).
- locale: User’s locale such as en-US.

Best practices

Always include user_id once the user is identified.
If sending events before identification, fetch anonymous_id from the browser and ensure it’s passed to Usermaven later in the identify call to stitch sessions.
Use UTC ISO 8601 format or a millisecond UNIX timestamp for accurate time tracking.
Include relevant custom fields under user, company, or event attributes to enrich profiles and segments.
Send events to the official Usermaven endpoint:
https://events.usermaven.com/api/v1/s2s/event?token=YOUR_API_KEY

Following these practices ensures accurate identity resolution and reliable analytics across your product and marketing data.

If you have any questions, feel free to get in touch with us at support@usermaven.com