Skip to Content

Sending events through the HTTP endpoint

Usermaven provides a powerful HTTP API for direct event collection. This guide provides a comprehensive walkthrough for authenticating requests, structuring event payloads, and utilizing advanced features like identity stitching and historical import.

Getting your API credentials

To interact with the API, you need two credentials from your Usermaven workspace: an API Key and a Server Token.

  1. Log in to your Usermaven account and select your workspace.
  2. Navigate to Workspace Settings > Setup.
  3. Select the HTTP API tab.
  4. Copy both your API Key and Server Token.

API credentials location in Usermaven settings

Sending events: The fundamentals

API endpoint and authentication

To send an event, make a POST request to the following endpoint. Authentication is handled via a single combined token in the URL query string.

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

How to format your authentication token

The token parameter is a single string created by joining your API Key and Server Token with a period (.).

Format: YOUR_API_KEY.YOUR_SERVER_TOKEN

Event payload structure

Events are sent as JSON objects in the POST request body. A well-structured payload ensures your data is processed correctly.

Key field descriptions

  • api_key (Required): Your workspace-specific API Key.
  • event_type (Required): The name of the event (e.g., user_identify, plan_upgraded).
  • user.id (Required): The unique ID for the user from your database.
  • user.anonymous_id (Conditional): The ID from the browser cookie. Only include this on the first user_identify call to connect a user’s pre-login activity.
  • user.email (Recommended): The user’s email address.
  • user.created_at (Recommended): The ISO 8601 timestamp for when the user signed up.
  • event_id (Optional): A unique ID for the event. Leave empty ("") to have Usermaven generate one. Provide a custom ID to prevent duplicate event submissions.
  • _timestamp (Optional): A UTC timestamp in milliseconds, used for importing historical events.

Minimal example: Identifying a user

This is the most basic payload required to identify a user and create their profile.

{
  "api_key": "YOUR_API_KEY", // change this with your API key
  "event_type": "user_identify", // change this with your event type
  "user": {
    "id": "usr_1a2b3c4d5e", // User ID from your database
    "email": "hello@usermaven.com", // User email
    "created_at": "2023-01-20T09:55:35Z" // User signup date in ISO 8601 format
  }
}

The user_identify event is crucial. It creates and updates user profiles in the Contacts Hub > Users view and is the foundation for attributing all subsequent user activity.

Sending custom events with attributes

For any action other than identifying a user, use a custom event_type and add relevant details in the event_attributes object.

{
  "api_key": "YOUR_API_KEY", // change this with your API key
  "event_type": "plan_upgraded", // change this with your event type
  "event_attributes": {
    "plan_from": "basic",
    "plan_to": "premium",
    "amount": 100,
    "currency": "USD"
  },
  "user": {
    "id": "usr_1a2b3c4d5e" // User ID from your database
  }
}

Advanced event tracking

Identity stitching: Connecting anonymous and identified users

Identity stitching merges a user’s activity before and after they log in into a single, unified timeline. This is achieved by passing the anonymous_id from the browser on the first server-side user_identify event type call.

When anonymous_id is required

  • For the first server-side user_identify call for a user who had prior anonymous browser activity.
  • When you are doing server-side-only tracking and need to manually bridge sessions.

When anonymous_id is not needed

  • If the user is already identified via the usermaven("id", ...) call in the browser.
  • For all subsequent server-side events after the user has been successfully identified.
  • For users who sign up directly with no prior anonymous activity on your site.

Getting the anonymous_id from browser cookies

Use this helper function in your frontend code to retrieve the ID from the __eventn_id_ cookie and send it to your backend.

// Helper function to get Usermaven anonymous ID from browser
function getUsermavenAnonymousId() {
  const cookie = document.cookie
    .split('; ')
    .find(c => c.startsWith('__eventn_id_'));
  return cookie ? cookie.split('=')[1] : null;
}
 
// Example: Send it to your backend when the user signs up
const anonId = getUsermavenAnonymousId();
// fetch('/api/signup', { body: JSON.stringify({..., anonymousId: anonId }) });

Historical import: Sending past events

To import events that occurred in the past, include the _timestamp field in your payload.

The _timestamp must be a UTC timestamp in milliseconds. If omitted, Usermaven assigns the time the event was received.

{
  "api_key": "YOUR_API_KEY", // change this with your API key
  "event_type": "user_signup", // change this with your event type
  "_timestamp": 1632150122000, // UTC timestamp in milliseconds
  "user": {
    "id": "usr_past_user_001", // User ID from your database
    "email": "historical.user@example.com", // User email
    "created_at": "2021-09-20T12:00:00Z" // User signup date in ISO 8601 format
  }
}

Bulk events: Sending multiple events at once

To improve performance, you can send a JSON array of up to 20 event objects in a single POST request.

[
  {
    "api_key": "YOUR_API_KEY", // change this with your API key
    "event_type": "plan_upgraded", // change this with your event name
    "_timestamp": 1632150122000, // UTC timestamp in milliseconds
    "event_attributes": { "amount": 100, "currency": "USD" },
    "user": { "id": "user_123" }
  },
  {
    "api_key": "YOUR_API_KEY", // change this with your API key
    "event_type": "feature_used", // change this with your event name
    "_timestamp": 1632150123000, // UTC timestamp in milliseconds
    "event_attributes": { "feature_name": "advanced_analytics" },
    "user": { "id": "user_123" }
  }
]

Best practices and testing

Creating high-quality server-side events

For the most valuable analytics, structure your payloads with these layers of information:

  1. Envelope Data: The api_key and optional _timestamp.
  2. User & Company Data: The user object with ID and traits, and an optional company object for B2B contexts.
  3. Event Details: A clear event_type and rich event_attributes.
  4. Context Information: Add fields like ip, user_agent, url, and campaign parameters to enrich events and improve attribution. See the example below for a list of common context fields.
{
  "ip": "192.168.1.1",
  "user_agent": "Mozilla/5.0...",
  "url": "[https://example.com/page](https://example.com/page)",
  "page_title": "Page Title",
  "doc_path": "/page",
  "campaign": {
    "source": "google",
    "medium": "cpc",
    "campaign": "summer_sale"
  },
  "library": {
    "name": "my_backend_service",
    "version": "1.2.3"
  }
}

Testing and validation

Use test workspaces. Always send test events to a separate development workspace in Usermaven before sending data to your production workspace.

Verification steps

  1. Check event delivery: Go to Configure > Events Activity in your dashboard to see events arriving in real-time.
  2. View user profiles: Check Contacts Hub > People to ensure users are being identified correctly.
  3. Test identity stitching:
    • Open your site in an incognito window.
    • Browse several pages anonymously.
    • Sign up or log in, triggering your user_identify event call with the anonymous_id.
    • Check the new user’s timeline in Usermaven to verify that their pre-login pageviews are correctly attributed to their profile.

Common issues and troubleshooting

  • Events not appearing: Double-check that your combined token is formatted correctly (API_KEY.SERVER_TOKEN) and that your request Content-Type is application/json.
  • Anonymous activity not connecting: Ensure you are successfully retrieving the anonymous_id from the cookie and including it in the first user_identify event call only.

Additional resources

If you have questions about implementing the Usermaven API, reach out to our support team via in-app chat or email at support@usermaven.com.

Last updated on
Installing Usermaven