Cohort Webhooks

Amplitude Cohort webhooks enables customers to receive cohort updates to their own webhook endpoints. This allows for custom data enrichment, filtering, or aggregation based on the specific requirements of the webhook endpoint or internal systems. The transformed cohort data then integrates into marketing automation platforms or other systems, which enables 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

1. 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.

2. Create a new destination.

   1. In Amplitude Data, click Catalog and select the Destinations tab.
   2. In the Cohorts section, click Webhook.

3. 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.

4. 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

5. 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 more details below.

6. When satisfied with your configuration, click Save to complete the setup process.

Establish Cohort syncs to your destination

1. In Amplitude, open the cohort you want to export.
2. Click Sync, and choose Webhook.
3. Select the defined webhook destination.
4. Select the sync cadence.
5. Click Sync to begin the sync.

FreeMarker Templating Language

See the FreeMarker guide to creating templates for more help.

Example template to send cohort updates

 1{
 2    "cohort_name": "${input.cohort_name}",
 3    "cohort_id": "${input.cohort_id}",
 4    "in_cohort": ${input.in_cohort},
 5    "computed_time": "${input.computed_time}",
 6     "message_id": "${input.message_id}",
 7    "users": [
 8     <#list input.users as user>
 9     {
10         "user_id": "${user.user_id}"
11      }<#sep>,
12     </#list>
13    ]
14}

This template creates and sends this JSON payload to the Webhook endpoint:

 1{
 2    "cohort_name": "My Test Cohort",
 3    "cohort_id": "7khm89cz",
 4    "in_cohort": true,
 5    "computed_time": "1692206763",
 6    "message_id": "9baaa88f-9d46-4ee5-a946-be0c6aea0046::enter::0",
 7    "users": [
 8      {
 9         "user_id": "user_one@example.com"
10      },
11      {
12         "user_id": "user_two@example.com"
13      },
14      {
15         "user_id": "user_three@example.com"
16      }
17    ]
18}

Example template to send cohort updates per user

Some webhook destinations need a list of users as a batch. For these cases, you can update the template to match. The example below shows the cohort name and cohort id as a single boolean property which determines if the user is in the cohort or not.

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

This template creates and sends this JSON payload to the Webhook endpoint:

 1{
 2      {
 3         "user_id": "user_one@example.com",
 4         "amplitude_My Test Cohort_7khm89cz": true
 5      },
 6      {
 7         "user_id": "user_two@example.com"
 8         "amplitude_My Test Cohort_7khm89cz": true
 9      },
10      {
11         "user_id": "user_three@example.com"
12         "amplitude_My Test Cohort_7khm89cz": true
13      }
14}

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.