How to send events to Usermaven from any application using webhooks

This guide will show you how to connect third-party applications (like CRMs, payment processors, or call tracking tools) to UserMaven. By using webhooks, you can send valuable event data from these systems into UserMaven, giving you a complete, unified view of your customer’s journey.

The easiest way to accomplish this is with an automation platform like Zapier or Make.com. These tools act as a “translator,” catching the webhook from the source app, reformatting it, and sending it to UserMaven’s Events API.

In this guide you will learn:

• The basic flow for tracking events from a third-party app like Stripe
• The advanced flow for stitching anonymous events with CallRail
• Additional example for tracking lead stages with HubSpot

What you need to get started

1. Your API Key and Server Token: In your Usermaven dashboard, navigate to Workspace Settings > Setup > HTTP API to find these.
2. A Zapier Account: The “Webhooks by Zapier” action may require a paid plan.
3. An account with the third-party app you want to connect.

Part 1: The basic flow (tracking known users with Stripe)

This method is perfect for tracking events that happen after a user is already identified in your system. A great example is tracking successful payments from Stripe.

Step 1: Set up the trigger in Zapier

1. In Zapier, click Create Zap.
2. Choose your trigger app (Stripe) and the event (“Payment Succeeded”).
3. Connect your Stripe account and test the trigger to pull in sample data.

Step 2: Configure the webhook action

This step sends the data to Usermaven in the correct format.

1. Create an Action step and select Webhooks by Zapier.

2. Choose the Action Event: POST.

3. Configure the action settings:

   URL You must construct the URL with a special token parameter by joining your API Key and Server Token with a period (.).

   • Format: YOUR_API_KEY.YOUR_SERVER_TOKEN
   • Full URL: https://events.usermaven.com/api/v1/s2s/event?token=YOUR_API_KEY.YOUR_SERVER_TOKEN

   Paste this full URL into the URL field.

   Payload Type Set this to json.

   Data Map data from Stripe to Usermaven’s API fields. The structure is nested, so pay close attention to the field names (e.g., user.id).

Example final JSON payload

The Zapier mapping above will generate a JSON payload that looks like this:

{
  "api_key": "YOUR_API_KEY",
  "event_type": "Subscription Payment Succeeded",
  "user": {
    "id": "usr_1a2b3c4d5e"
  },
  "event_attributes": {
    "amount": 2900,
    "invoiceUrl": "https://invoice.stripe.com/..."
  }
}

Step 3: Test and publish

Test the action in Zapier. You should see the new event appear in your Usermaven Events Activity stream and on the correct user’s timeline. If it’s successful, publish your Zap.

Part 2: The advanced flow (stitching anonymous events with CallRail)

This is for when the event happens before you know who the user is, like a phone call from your website. The goal is to link the call to the user’s anonymous Browse session by capturing the Usermaven anonymous_id.

Step 1: The one-time website setup

Add this script to your website to act as a bridge: it gets the anonymous_id from the Usermaven cookie and makes it available to CallRail’s tracking script. Place it on every page just before the closing </body> tag.

<script type="text/javascript">
  function getUsermavenAnonymousId() {
    const cookie = document.cookie
      .split('; ')
      .find(c => c.startsWith('__eventn_id_'));
    return cookie ? cookie.split('=')[1] : null;
  }
 
  window.addEventListener('load', function() {
    try {
      var mavenAnonymousId = getUsermavenAnonymousId();
      if (mavenAnonymousId && typeof cr_custom_fields !== 'undefined') {
        cr_custom_fields.usermaven_anonymous_id = mavenAnonymousId;
      }
    } catch (e) {
      console.error("Error bridging Usermaven and CallRail:", e);
    }
  });
</script>

Step 2: Configure the webhook in Zapier

1. Trigger: In Zapier, create a new Zap with CallRail as the trigger and “New Completed Call” as the event.
2. Action: Create a Webhooks by Zapier action with the POST method. Configure the URL and Payload Type as described in Part 1.
3. Data Mapping: Map the custom field you created in Step 1.

Example final JSON payload

This configuration will send the following JSON to Usermaven:

{
  "api_key": "YOUR_API_KEY",
  "event_type": "Call Completed",
  "user": {
    "anonymous_id": "5zdta4zak9" 
  },
  "event_attributes": {
    "duration": 345,
    "callerNumber": "+15551234567"
  }
}

When this user later identifies themselves, their pre-login activity, including this call, will be stitched into their permanent profile.

Part 3: Additional example (tracking lead stages with HubSpot)

A powerful use case is to track when a user’s status changes in your CRM. This allows you to analyze what product actions lead to a user becoming a Marketing Qualified Lead (MQL) or Sales Qualified Lead (SQL).

This example will send an event to Usermaven whenever a contact’s “Lifecycle Stage” is updated in HubSpot.

Step 1: Set up the HubSpot trigger

1. In Zapier, create a new Zap with HubSpot as the trigger.
2. Choose the event “Updated Contact Property”.
3. In the trigger options, specify “Lifecycle Stage” as the property to monitor. This ensures the Zap only runs when that specific property changes.
4. Test the trigger to get sample data from a recently updated contact.

Step 2: Configure the webhook action

1. Create an Action step using Webhooks by Zapier with the POST method.
2. Configure the URL and Payload Type as described in Part 1.
3. Data Mapping: Map the contact’s identifier and their new lifecycle stage.

Example final JSON payload

The finished payload sent to Usermaven will look like this, using a non-email User ID:

{
  "api_key": "YOUR_API_KEY",
  "event_type": "Lifecycle Stage Updated",
  "user": {
    "id": "usr_1a2b3c4d5e"
  },
  "event_attributes": {
    "new_stage": "Sales Qualified Lead",
    "previous_stage": "Marketing Qualified Lead",
    "source": "SALES"
  }
}

With this data, you can build funnels and reports in Usermaven to see which features are most used by users who eventually become Sales Qualified Leads.

Troubleshooting and common questions

• I’m getting a 401 Unauthorized error. This means your API key or token is incorrect. Ensure the token parameter in your URL is formatted exactly as API_KEY.SERVER_TOKEN with your valid credentials.

• I’m getting a 400 Bad Request error. This usually means the data sent was incomplete or malformed. Ensure your payload includes api_key, event_type, and a user object containing at least an id or an anonymous_id.

• My events aren’t stitched to the right user. For basic flows, double-check that the user.id you send from the webhook (e.g., your internal ID or the user’s email) is the exact same identifier you use in your user_identify event or browser-side identify() calls. For advanced flows, use your browser’s developer tools to ensure the custom script on your website is running correctly and passing the anonymous_id.