Cohort Sync - Mixpanel

Overview

Cohort Sync allows you to send your Mixpanel Cohorts to other destinations for audience targeting. This enables you to leverage Mixpanel’s powerful segmentation capabilities across your marketing and engagement tools.

This page highlights integrations that send Mixpanel Cohorts to external destinations. Learn more about integrations that import data from other destinations into Mixpanel and integrations that export data from Mixpanel to data warehouses.

Featured Integrations

AB Tasty

A/B testing platform

Airship

Mobile engagement platform

Appcues

User onboarding platform

Apptimize

Mobile A/B testing

Braze

Customer engagement platform

Chameleon

Product guidance platform

CleverTap

Marketing automation

Facebook Ads

Social media advertising

Google Ads

Search and display advertising

Insider

Growth management platform

Iterable

Cross-channel marketing

Kameleoon

Personalization platform

Leanplum

Mobile marketing automation

Mailchimp

Email marketing platform

Marketo

Marketing automation

MoEngage

Customer engagement platform

OneSignal

Push notification service

Salesforce Marketing Cloud

Marketing automation

Segment

Customer data platform

Taplytics

Mobile experimentation

VWO

Testing and optimization

WebEngage

Marketing automation

Xtremepush

Engagement platform

Custom Webhooks

For destinations that do not have a native Mixpanel integration, you can sync cohorts to a custom webhook URL that you provide.

Prerequisites

A paid Mixpanel plan
A Mixpanel project
A webhook server (you can create a dummy webhook for testing purposes using webhook.site)
The webhook server should send back events to Mixpanel to track actions like Message sent (optional)

Setting up the Webhook

To create a new Custom Webhook destination, navigate to the Integrations UI and add a new Webhook connection. All you need to provide is a name for the connection and the URL of your webhook server. Optional: Basic Authentication when calling the webhook URL provided

From this point onward, you can sync any cohort to this connection from the cohorts page.

Exported Properties

Mixpanel will automatically include email, mixpanel_distinct_id, first_name, and last_name to identify the user. If you need to add extra properties, feel free to add in the Properties to Export field where we populate some pre-existing fields for you to choose.

Webhook Format

Our webhook format has the following structure in the body of a POST request: Action: The action defines the type of message we are sending:

members: All members of the cohort, sent the first time the cohort is being synced or to refresh the cohort
add_members: A diff consisting of users that have entered the cohort since the last sync
remove_members: A diff consisting of users who have exited the cohort since the last sync

Parameters:

mixpanel_project_id: the ID for Mixpanel project that produced this cohort
mixpanel_cohort_id: unique identifier of the cohort
mixpanel_cohort_name: The cohort name, editable via the Mixpanel UI
mixpanel_cohort_description: The cohort description, editable via the Mixpanel UI
mixpanel_session_id: An identifier for this export
page_info: An object containing “total_pages” and “page_count”
members: The list of users being added or removed from the cohort

Example webhook payload:

{
  "action": "members",
  "parameters": {
    "mixpanel_project_id": "{mixpanel_project_id}",
    "mixpanel_cohort_name": "{mixpanel_cohort_name}",
    "mixpanel_cohort_id": "{mixpanel_cohort_id}",
    "mixpanel_cohort_description": "description",
    "mixpanel_session_id": "mixpanel_session_id",
    "page_info": {
      "total_pages": 10,
      "page_count": 6
    },
    "members": [
      {
        "email": "string",
        "mixpanel_distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "phone_number": "xxx-xxx-xxxxx"
      },
      {
        "email": "string",
        "mixpanel_distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "phone_number": "xxx-xxx-xxxxx"
      }
    ]
  }
}

Expected Response Format

We expect a JSON response of the following shape:

{
  "action": "add_members",
  "status": "success",
  "error": {
    "message": "some error message; this will be displayed in our UI",
    "code": 400
  }
}

action: Must match the action we sent
status: Must be either success or failure
error: Only expected on failure
- message: details about the error
- code: an HTTP status code

Sync Behavior

Cohorts are synced once every 30 minutes (for dynamic syncs). The batch size is set to 1000 users per call to add_members or remove_members.

Full Sync

Full syncs are only performed when:

We sync the cohort for the first time
We store the snapshot of the cohort state for the last successful sync for 3 days. If your webhook server is down (returns a 429 or 5XX error) for more than 3 days, the snapshot expires and we do a full sync

Subsequent syncs include only differences in membership since the previous successful sync in order to preserve bandwidth.

Diffing

Every time we perform a successful sync to your webhook, we store a snapshot of the cohort as of that time. This snapshot is valid for 3 days. Subsequent syncs use the last successful snapshot of the cohort to compute the number of users added and removed (the diff). We send this diff to your webhook via the add_members and remove_members calls.

Example Webhook Sync Scenario

Consider A, B, C, D, E, and F as users. The sync interval is 30 minutes. T represents the time when the sync is created in our UI.

T: add_members(A, B, C, D) | remove_members()
T+10mins: B, D leave the cohort
T+20mins: E, F join the cohort
T+30mins: add_members(E, F) | remove_members(B, D)
T+1h: add_members() | remove_members() (no changes)

Failed Syncs

We pause syncs when your server returns a non-transient error (400, 401, 403, 404). Please use the appropriate HTTP status code to indicate a non-transient error; this helps avoid added load. We record failed syncs in our UI and display the error message returned in the response from your webhook server. A notification email is sent to all users who have set up cohort syncs when the syncs pause due to an error. We retry syncs 5 times over 60 secs with exponential backoff in response to 5xx and 429 status codes. After this point, we will wait until the next scheduled sync to retry.

Integration Examples

Braze
Facebook Ads
Google Ads

Braze Integration

The Mixpanel Braze integration exports Mixpanel Cohorts into Braze. This allows you to send Braze campaign messages to targeted cohorts that are created in Mixpanel.

Required Credentials

In order to set up the integration, you must use a Data Import Key and a Braze Instance URL to connect a Mixpanel instance with a Braze instance.

Set Up the Integration

Select Settings > Integrations tab in the bottom left navigation bar of Mixpanel
Select the Braze integration tab. Click Connect
Enter the Data Import Key and select a Braze Instance
Click Continue to complete the process

If you set a User ID Property, it should be a Mixpanel user property that matches the Braze External ID. If you do not select one, Mixpanel will default to using the $braze_external_id property to match users between Braze and Mixpanel.

Export a Cohort

Click Data Management at the top of Mixpanel. Navigate to Cohorts
Select the cohort to send to Braze. Select Export to Braze
Select a One-time export or a Dynamic sync. Click Begin Sync

Use the Cohort in Braze

Select Segments tab under Engagement in Braze
Click Create Segment
After naming the Segment, select “Mixpanel Cohorts” from the filter dropdown
Select “includes” value and search for your exported cohort
Click Save

Matching Users

Projects using the Simplified ID merge system must have the $user_id in Mixpanel match the user identifier in the partner service.

In order to match Mixpanel users to ones on Braze’s end, the user in Mixpanel should have a profile property named $braze_external_id with the value you have assigned in Braze to the same user as external_user_id.

Facebook Ads Integration

Export Mixpanel cohorts to Facebook Ads to use targeted advertisements in Facebook.

You must have a Facebook Business account connected to Business Manager to use this integration.

Enable the Integration

Select Settings > Integrations tab in the bottom left navigation bar of Mixpanel
From the Integrations page, click the Facebook Ads dropdown
Select your Facebook Ad Account ID and your connector name
Choose user property where you’re storing device advertising ID (optional)

Export a Cohort

Navigate to Data Management > Cohorts
Select the cohort that you want to export
Click Export to Facebook. Select either a one-time sync or a dynamic sync
Click Start Sync

Sync Types

One-Time Export: Mixpanel sends Facebook a static export of users who currently qualify for the cohort. The cohort data will not be updated in Facebook after a one-time export.Dynamic Sync: Mixpanel initiates a sync between a cohort and Facebook every two hours. The exported cohort will be updated every two hours to reflect the most recent list of users in a cohort.

Use the Cohort in Facebook Ads

Log in to Facebook Business Manager
Select the Menu in top navigation
Click on Audiences
The Mixpanel Cohort is available in the Audience list as mixpanel_<Cohort Name>_<Cohort ID>

Data Requirement

Meta uses email addresses as the primary identifier to match users in your cohort with users in their system. If an email address is not available, Meta may instead attempt to match using other identifiers such as a phone number, first and last name, or a device advertising ID.To use this integration, each user profile must include either an email address or a device advertising ID. In addition to the email (if present), your system will send the following user profile properties (if available): first name, last name, phone number, advertising ID, and distinct_id.If Meta is unable to match a cohort member with a user in their system, that member will be excluded from the resulting Meta audience.

FAQ

Does page_count in webhook requests start from 0 or 1?

The page_count starts from 1.

Are users within cohort re-synced when webhook calls fail?

Even though we just sync a diff of users for each cohort there can be failures that occur mid sync. In a case like this, we do not have a mechanism to keep track of users that were already synced for a cohort when the failure occurs in between the sync process. So we start the sync from the top again. This can cause issues like users being synced again.

What can go wrong for custom webhooks when users are synced again after failure scenarios?

If users are set up for some action upon arrival, failure and recovery could trigger a duplicate action for the same user. This can be fixed on the custom webhook server-side by keeping track of users who have been already targeted with the action.

How are actions tracked in Mixpanel?

The actions are not automatically tracked in Mixpanel as they occur on the customer-side webhook server. Customers have to explicitly track events back to Mixpanel in order to use them on the Mixpanel platform.

Introduction

Quickstart

Data Ingestion

Data Structure

Reports & Analysis

Advanced Features

Data Export

Administration

​Overview

​Featured Integrations

AB Tasty

Airship

Appcues

Apptimize

Braze

Chameleon

CleverTap

Facebook Ads

Google Ads

Insider

Iterable

Kameleoon

Leanplum

Mailchimp

Marketo

MoEngage

OneSignal

Salesforce Marketing Cloud

Segment

Taplytics

VWO

WebEngage

Xtremepush

​Custom Webhooks

​Prerequisites

​Setting up the Webhook

​Exported Properties

​Webhook Format

​Expected Response Format

​Sync Behavior

​Full Sync

​Diffing

​Example Webhook Sync Scenario

​Failed Syncs

​Integration Examples

​Braze Integration

​Required Credentials

​Set Up the Integration

​Export a Cohort

​Use the Cohort in Braze

​Matching Users

​Facebook Ads Integration

​Enable the Integration

​Export a Cohort

​Sync Types

​Use the Cohort in Facebook Ads

​Data Requirement

​Google Ads Integration

​Setup Requirements

​Enable the Integration

​Export a Cohort

​Matching Users

​FAQ

Build docs developers (and LLMs) love

Overview

Featured Integrations

Custom Webhooks

Prerequisites

Setting up the Webhook

Exported Properties

Webhook Format

Expected Response Format

Sync Behavior

Full Sync

Diffing

Example Webhook Sync Scenario

Failed Syncs

Integration Examples

Braze Integration

Required Credentials

Set Up the Integration

Export a Cohort

Use the Cohort in Braze

Matching Users

Facebook Ads Integration

Enable the Integration

Export a Cohort

Sync Types

Use the Cohort in Facebook Ads

Data Requirement

Google Ads Integration

Setup Requirements

Enable the Integration

Export a Cohort

Matching Users

FAQ