Cohort Webhooks

Cohort webhooks send cohort updates to your webhook endpoints. Use them for custom data enrichment, filtering, or aggregation based on the endpoint's requirements. Integrate the transformed data into marketing automation platforms or other systems to power personalized campaigns with up-to-date cohort insights.

Considerations

• Enable this integration in each Amplitude project you want to use it in.
• You need a paid Amplitude plan to use Cohort Webhooks.
• Cohort Webhooks send add or remove batches to the destination. The destination must process each batch within 1 to 2 seconds (including network latency) so Amplitude receives a 200 OK response within retry limits. If the destination doesn't respond in time, the call times out and retries, which may produce duplicate payloads.
• Amplitude recommends testing destination endpoint latency with tools like Postman to confirm responses fall within the expected window.
• If processing takes longer, use an async API pattern that returns a 200 OK immediately and handles the payload asynchronously, for example with in-memory queues.

Set up the integration

1. To configure streaming from Amplitude to your webhook, collect the following information:

   • Webhook URL: The destination URL Amplitude uses 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 your URL must accept payloads from any Amplitude host.

4. Every webhook sync includes two preset headers:

   • Content-Type: application/json
   • User-Agent: Amplitude/Webhook/1.0

   You can define five more headers after the preset headers. To create a new header:

   1. Enter the header name in the left text box.
   2. Enter the header value in the right 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:

   1. Send the default Amplitude payload, which follows the Amplitude cohort format.
   2. Customize the payload using an Apache FreeMarker template. Refer to FreeMarker Templating Language for details.

6. Click Save to complete the setup.

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. (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.
5. Select the sync cadence.
6. Click Sync to begin the sync.

FreeMarker Templating Language

Refer to 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>
   ]
}

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>
]
}

Example template for sending cohort updates per user

Some webhook destinations need a list of users as a batch. The following example sets the cohort name and cohort ID as a single boolean property indicating whether the user is in the cohort.

[ < #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 > ]

Template reference

• FreeMarker replaces ${ ... } 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 object follows the same format as the example payloads.
• The input object has the following format:
  • cohort_name string. The display name of the cohort.
  • cohort_id string. The unique identifier of the cohort.
  • in_cohort boolean. Indicates whether this batch of users is entering or leaving the cohort.
  • computed_time string. The time Amplitude computed this update, as Unix epoch time in seconds (for example, "1692206763").
  • message_id string. The unique identifier of this update message. Use this value to de-duplicate on retry.
  • users list of JSON objects. The 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.