Cohort Webhooks

Amplitude CDP’s cohort webhook allows you to receive cohort updates to your webhook endpoints. This allows for custom data enrichment, filtering, or aggregation based on the specific requirements of the webhook endpoint or internal systems. Integrate the transformed data into marketing automation platforms or other systems, enabling personalized and targeted marketing campaigns with up-to-date cohort insights.

Considerations

You must enable this integration in each Amplitude project you want to use it in.
You need a paid Amplitude plan to use Cohort Webhooks.

Setup

To configure streaming from Amplitude to your webhook, collect the following information:
- Webhook URL: The destination URL Amplitude should use to send events and users.
- Header Information: You can set up to five extra headers for the webhook request.
Create a new destination.
1. In Amplitude Data, click Catalog and select the Destinations tab.
2. In the Cohorts section, click Webhook.
Enter the URL endpoint for the webhook. For example, https://mycompany.com/webhook.
Amplitude doesn't have a single IP address for forwarding events and users, so ensure that your URL can receive payloads from any Amplitude hosts.
There are two preset headers for every webhook sync:
- Content-Type: application/json
- User-Agent: Amplitude/Webhook/1.0
After these preset headers, you can define five more headers. To create a new header:
1. Enter the header name on the left side text box
2. Enter the header value on the right side text box
3. A new header row appears if the limit isn't reached
Define the payload you want to receive in the webhook. You can choose to:
1. Send the default Amplitude payload which follows the Amplitude cohort format.
2. Customize the payload using an Apache FreeMarker template. See FreeMarker Templating Language for more information.
When satisfied with your configuration, click Save to complete the setup process.

Establish Cohort syncs to your destination

In Amplitude, open the cohort you want to export.
Click Sync, and choose Webhook.
Select the defined webhook destination.
(Optional) Select up to 50 user properties to carry along with the user. Amplitude adds the selected properties to the user payload, and makes them accessible in the FreeMarker template.
Select the sync cadence.
Click Sync to begin the sync.

FreeMarker Templating Language

See the FreeMarker guide to creating templates for more help.

Example template for sending user ID only cohort updates

{
   "cohort_name": "${input.cohort_name}",
   "cohort_id": "${input.cohort_id}",
   "in_cohort": ${input.in_cohort?c},
   "computed_time": "${input.computed_time}",
   "message_id": "${input.message_id}",
   "users": [
   <#list input.users as user>
   {
      "user_id": "${user.user_id}"
   }<#sep>,
   </#list>
   ]
}

{
   "cohort_name": "${input.cohort_name}",
   "cohort_id": "${input.cohort_id}",
   "in_cohort": ${input.in_cohort?c},
   "computed_time": "${input.computed_time}",
   "message_id": "${input.message_id}",
   "users": [
   <#list input.users as user>
   {
      "user_id": "${user.user_id}"
   }<#sep>,
   </#list>
   ]
}

{
    "cohort_name": "My Test Cohort",
    "cohort_id": "7khm89cz",
    "in_cohort": true,
    "computed_time": "1692206763",
    "message_id": "9baaa88f-9d46-4ee5-a946-be0c6aea0046::enter::0",
    "users": [
      {
         "user_id": "user_one@example.com"
      },
      {
         "user_id": "user_two@example.com"
      },
      {
         "user_id": "user_three@example.com"
      }
    ]
}

{
    "cohort_name": "My Test Cohort",
    "cohort_id": "7khm89cz",
    "in_cohort": true,
    "computed_time": "1692206763",
    "message_id": "9baaa88f-9d46-4ee5-a946-be0c6aea0046::enter::0",
    "users": [
      {
         "user_id": "user_one@example.com"
      },
      {
         "user_id": "user_two@example.com"
      },
      {
         "user_id": "user_three@example.com"
      }
    ]
}

Example template for sending user with user properties cohort updates

{
    "cohort_name": "${input.cohort_name}",
    "cohort_id": "${input.cohort_id}",
    "in_cohort": ${input.in_cohort?c},
    "computed_time": "${input.computed_time}",
     "message_id": "${input.message_id}",
    "users": [
     <#list input.users as user>
     {
         "user_id": "${user.user_id}",
         "user_properties": {
            <#list input.user_properties?keys as key>
                <#assign value = input.user_properties[key]>
                "${key}": <#if value?is_number || value?is_boolean>${value}<#else>${UtilClass.toJsonString(value)}</#if><#if key_has_next>,</#if>
            </#list>
        }
      }<#sep>,
     </#list>
]
}

{
    "cohort_name": "${input.cohort_name}",
    "cohort_id": "${input.cohort_id}",
    "in_cohort": ${input.in_cohort?c},
    "computed_time": "${input.computed_time}",
     "message_id": "${input.message_id}",
    "users": [
     <#list input.users as user>
     {
         "user_id": "${user.user_id}",
         "user_properties": {
            <#list input.user_properties?keys as key>
                <#assign value = input.user_properties[key]>
                "${key}": <#if value?is_number || value?is_boolean>${value}<#else>${UtilClass.toJsonString(value)}</#if><#if key_has_next>,</#if>
            </#list>
        }
      }<#sep>,
     </#list>
]
}

{
 "cohort_name": "My Test Cohort",
 "cohort_id": "7khm89cz",
 "in_cohort": true,
 "computed_time": "1692206763",
 "message_id": "9baaa88f-9d46-4ee5-a946-be0c6aea0046::enter::0",
 "users": [
   {
     "user_id": "user_one@example.com",
     "user_properties": {
       "name": "John Doe",
       "country": "US",
       "city": "San Francisco"
     }
   },
   {
     "user_id": "user_two@example.com",
     "user_properties": {
       "name": "Jane Smith",
       "country": "US",
       "city": "New York"
     }
   },
   {
     "user_id": "user_three@example.com",
     "user_properties": {
       "name": "Alice Johnson",
       "country": "US",
       "city": "Los Angeles"
     }
   }
 ]
}

{
 "cohort_name": "My Test Cohort",
 "cohort_id": "7khm89cz",
 "in_cohort": true,
 "computed_time": "1692206763",
 "message_id": "9baaa88f-9d46-4ee5-a946-be0c6aea0046::enter::0",
 "users": [
   {
     "user_id": "user_one@example.com",
     "user_properties": {
       "name": "John Doe",
       "country": "US",
       "city": "San Francisco"
     }
   },
   {
     "user_id": "user_two@example.com",
     "user_properties": {
       "name": "Jane Smith",
       "country": "US",
       "city": "New York"
     }
   },
   {
     "user_id": "user_three@example.com",
     "user_properties": {
       "name": "Alice Johnson",
       "country": "US",
       "city": "Los Angeles"
     }
   }
 ]
}

Example template for sending cohort updates per user

Some webhook destinations would need a list of users as a batch. In the below example, set the cohort name and cohort id as a single boolean property determining whether the user is in the cohort or not.

[ < #list input.users.iterator() as user > {
    'user_id': '${user.user_id}',
    'amplitude_${input.cohort_name}_${input.cohort_id}': $ {
        input.in_cohort
    }
} < #if user_has_next > , < /#if></#list > ]

[ < #list input.users.iterator() as user > {
    'user_id': '${user.user_id}',
    'amplitude_${input.cohort_name}_${input.cohort_id}': $ {
        input.in_cohort
    }
} < #if user_has_next > , < /#if></#list > ]

{
   [
      {
         "user_id": "user_one@example.com",
         "amplitude_My Test Cohort_7khm89cz": true
      },
      {
         "user_id": "user_two@example.com"
         "amplitude_My Test Cohort_7khm89cz": true
      },
      {
         "user_id": "user_three@example.com"
         "amplitude_My Test Cohort_7khm89cz": true
      }
    ]
}

{
   [
      {
         "user_id": "user_one@example.com",
         "amplitude_My Test Cohort_7khm89cz": true
      },
      {
         "user_id": "user_two@example.com"
         "amplitude_My Test Cohort_7khm89cz": true
      },
      {
         "user_id": "user_three@example.com"
         "amplitude_My Test Cohort_7khm89cz": true
      }
    ]
}

Other useful information for templates

FreeMarker replaces the ${ ... } constructs with the value of the expression inside the curly braces.
input is a reserved variable that refers to the event as an object. The "input" has the same format as the example payload above.
input has the following below format:
- cohort_name string. The display name of the cohort.
- cohort_id string. The unique identifier of the cohort.
- in_cohort boolean. Show if this batch of users is entering/leaving the cohort.
- compute_time string. The time when Amplitude computes this update.
- message_id string. The unique identifier of this update message. When a retry happens, you can use this value to de-duplicate.
- users list of JSON objects. The actual user payload.
  - user_id string. The Amplitude user_id of the user.
  - user_properties JSON object. The user properties selected for this user during this cohort sync.