Webhooks Streaming

Amplitude's Webhook integration lets you forward Amplitude events and users to custom webhooks. This is a lightweight way to send a stream of event and user data from Amplitude to a URL of your choosing.

Use cases

• Workflow automation: Webhooks automate workflows and connect disparate systems by triggering actions based on specified events or conditions. For example, create a webhook to automate the capture and recording of user consent. When a user accepts the terms of service, the webhook triggers and Amplitude logs the event.
• Flexibility beyond standard streaming integrations: Webhooks provide customization beyond standard streaming integrations, enabling real-time data exchange and tailored interactions. For example, use a webhook to send specific event data from Amplitude to Braze, a use case the native Amplitude Braze streaming integration doesn't support. This involves transforming an Amplitude user property named newsletters, an array with market and newsletter_names, into a format suitable for Braze.

Set up the integration

Prerequisites

To configure streaming from Amplitude to your webhook, you need 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 sync

1. In Amplitude Data, click Catalog and select the Destinations tab.
2. In the Event Streaming section, click Webhook.
3. Enter a sync name, then click Create Sync.

Enter webhook URL

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 your URL can receive payloads from any Amplitude hosts.

For details on what happens when a webhook call fails, refer to Amplitude's retry mechanism.

Select headers

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

Configure event forwarding

Under Send Events, enable the toggle ("Events are sent to Webhook") to stream events to the webhook. When enabled, Amplitude automatically forwards events to the webhook when it ingests them. This integration doesn't send events on a schedule or on-demand.

1. Define the event payload you want to receive in the webhook. You can choose to:

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

2. In Select and filter events choose which events you want to send. Choose only the events you need in the webhook. Transformed events aren't supported.

Configure user forwarding

Under Send Users, enable the toggle ("Users are sent to Webhook") to stream users and their properties to the webhook. When enabled, Amplitude sends users to the webhook when it receives an event. Amplitude also forwards Amplitude Identify API calls to the webhook. This integration doesn't send users on a schedule or on-demand.

• Define the user payload you want to receive in the webhook. You can choose to:
  1. Send the default Amplitude payload, which follows the Amplitude user format.
  2. Customize the payload using an Apache FreeMarker template. Refer to the FreeMarker Templating Language section.

Enable sync

When you're satisfied with your configuration, at the top of the page toggle the Status to "Enabled" and click Save.

Amplitude's retry mechanism

Amplitude makes a delivery attempt first on each event or user. On failures, Amplitude makes nine more attempts over 4 hours, regardless of the error. Amplitude also has a retry mechanism within each attempt for 5xx errors and 429 throttling. Amplitude attempts an immediate retry with these policies:

1. Max attempts: 3.
2. Exponential retry with initial wait duration of 100 ms, doubling each time, with a 50% jitter.
3. Amplitude won't make another attempt after 4 seconds.

FreeMarker Templating Language

Amplitude uses Apache FreeMarker templates to customize your event payloads that you send to webhook.

• You can use the FreeMarker Templating Language (FTL) to transform Amplitude's events and user payloads into any other JSON schema expected by the Webhook destination.
• Amplitude's event format.
• Amplitude's user format. Note that based on how you use the Identify API, some fields might be different (for example, if you use device_id instead of user_id in your identify calls, the payload won't include user_id).

Example template for sending events

{
      <#if input.user_id??>
      "external_id" : "${input.user_id}",
      </#if>
      "name" : "${input.event_type}",
      "time" : "${input.event_time}",
      "properties" : {
            "email" : "${input.user_properties.email!}"
      }
}

Using this template results in sending this JSON payload to the Webhook endpoint:

{
    "external_id" : "some user id", // if `input.user_id` exists
    "name" : "click event",
    "time" : "2022-10-24T20:07:32.123",
    "properties" : {
        "email" : "some@email.com"
    }
}

Example template for sending users

{
      <#if input.user_id??>
      "external_id" : "${input.user_id}",
      </#if>
      <#if input.device_id??>
      "device_id" : "${input.device_id}",
      </#if>
      "time" : "${input.event_time}",
      "properties" : {
            "email" : "${input.user_properties.email!}"
      }
}

Using this template results in sending this JSON payload to the Webhook endpoint:

{
    "external_id" : "some user id", // if `input.user_id` exists
    "device_id" : "some user id", // if `input.user_id` exists
    "time" : "2022-10-24T20:07:32.123",
    "properties" : {
        "email" : "some@email.com"
    }
}

Handling event time formats

Amplitude by default sends the time as a UTC ISO-8601 formatted string such as "2022-02-28 20:07:01.795".

To modify this in different formats:

1. first set a datetime format setting: <#setting datetime_format="yyyy-MM-dd HH:mm:ss.S">
2. Use the following examples for conversion to different time formats:
   • Custom string format: "${input.event_time?datetime?string["dd.MM.yyyy, HH:mm"]}"
     • results in: "28.02.2022, 20:07"
   • Millisecond timestamp: "${input.event_time?datetime?long}"
     • results in: "1646107621000"

Other useful information for templates

• FreeMarker replaces the ${ ... } constructs with the actual value of the expression inside the curly braces.
• input is a reserved variable that refers to the event as an object, as defined in the Export API docs.
• input.event_type refers to the event_type field of the event.
• input.user_properties refers to the user properties dictionary.
• input.user_properties.email refers to the email field in user properties.
• The if directive checks whether the field exists. If it doesn't, the field is omitted from the output.
• The ! mark in the expression after input.user_properties.email includes a default value if no such field exists in the input. If you don't add a default value, the output contains an empty string instead.