Create an Event Streaming Integration

This guide walks through the basics of creating an Event Streaming tile in Amplitude. Event Streaming lets your users forward events from Amplitude in real time.

Event streaming considerations

Supported features

• Event Forwarding: Event forwarding sends Amplitude Track calls to a destination. Amplitude forwards both the raw event and merged or transformed events. Amplitude also sends the event_name and created_at to your destination.
• Event Filtering: Amplitude has fine-grained filtering options that let the user choose which events to send based on selected event types and property conditions.
• Event Selective Property Forwarding: The user can select which event, user, or group properties to include in the payload of forwarded events.
• Regular User Identify Forwarding (creating and updating a user): Enable the Identify Forwarding feature for your destination. This feature lets the destination send users and their properties created under the Identify API in real time. For more information, refer to the Identify documentation.
• User Property Mapping: The user can select an Amplitude user property to map to a field in your destination. This configuration also supports custom user identifiers.

Event streaming limitations

• User selective property forwarding: Forwarding certain event, group, or user properties from an event based on an allow list isn't supported.
• Forwarding arrays or object type properties: You can't forward arrays or object type properties. For example, you can't forward a property called cities, which is an array of cities.
• Change-based user Identify Forwarding: Amplitude doesn't automatically generate and forward an identify event when a user property changes during event ingestion.
• Property Value Transformation: You can't transform a property value or type to another value or type if the original event type isn't known.
• Selective Property Forwarding Type: Amplitude sends all custom properties forwarded by the user as strings.
• OAuth Authentication: Amplitude doesn't support OAuth, so partners need to generate their API key.
• Event Category name: Amplitude doesn't send the Event Category name.

Prepare an event streaming endpoint

1. Freemarker: Familiarize yourself with Freemarker, the template engine that Amplitude uses to send events.
2. Rate limits: Make sure your rate limits are as high as possible to minimize throttling. For example, Amplitude respects the rate limit that Braze communicates: 50,000 requests per minute for event tracking. Amplitude has a retry mechanism with exponential backoff that tries 9 times over 4 hours. This process should resolve temporary throttling.
3. Event limits: Make sure your event size limit is flexible enough for customer use cases.

4. Authentication method: Amplitude doesn't support OAuth, so partners need to generate their API key.
5. Endpoint flexibility: Amplitude generates a list of objects in a specific format. Make sure your endpoint handles this payload structure. Refer to the next section for a payload example.

Integration setup

Configure the integration tile that appears on the Destinations page in Amplitude.

1. From the Integration Portal page (Settings > Developer Portal), click Add New Destination.
2. Under Select Destination Type, choose Event Streaming.

Example setup modal

To view an example of a finished setup modal in Amplitude, navigate to Data Destinations in Amplitude, and add any integration marked with Event Streaming.

Configure the event streaming integration

The configuration page has two sections.

• The Configuration tab is where you configure your payload and what you expect to receive from Amplitude.
• The Testing tab summarizes your configurations, including your setup modal screen for your integration, parameters, and payload. The tab also lets you test your configuration using a custom payload.

Integration name

The integration name appears on the catalog page. The name must be globally unique across event streaming integrations.

Create parameters

This section lets you define the parameters that the URL, headers, and event body can use.

• Parameter Display Name: This is fully customizable, so use something descriptive. This value is the display name in Amplitude. For example, "REST API Endpoint & REST API Key."
• Parameter Name: The payload, URL, or header uses this ID for the corresponding parameter.

Customize user properties mapping

This section lets you define fields in the payload that the user can populate with an Amplitude user property of their choice. For example, most destinations use a field here for their user identifier and set it as required.

• Destination Property Name: This acts as both the field name and display name.
• Required Checkbox: If you check this option, the user can't forward events to your destination until they configure this field.

Customize events payload

Use the Customize Events Payload section to customize what's included in your payload.

• URL Endpoint: Depending on your endpoint, you can choose PUT, POST, or PATCH.
• REST API Headers: You can customize the API headers type to suit your use case. Some examples include:
  • Authorization: Contains the authentication credentials for HTTP authentication.
  • Content-Type: Tells the client the response media type, such as application/json or application/javascript. This header helps the client process the response body correctly.
  • WWW-Authenticate: The server may send this header as an initial response if it needs authentication before responding with the requested resource. Often this header appears with the 401 response code, which means "unauthorized."
  • Accept-Charset: The request sets this header and tells the server which character sets, such as UTF-8, ISO-8859-1, or Windows-1251, are acceptable by the client.
  • Cache-Control: The server defines the cache policy for this response. The client stores a cached response and reuses it until the Cache-Control header expires.
• Header Key & Header Value: This is fully customizable, so use something descriptive. For example, "API Key." This isn't included in the payload.

Example payload structure

{
  "external_id": "some user id",
  "app_id": "some app id",
  "name": "test_event_type",
  "time": "2022-01-06T17:29:04Z",
  "optional_property": "some Amplitude property",
  "optional_property_again": "some Amplitude property again",
  "properties" : {
        "test_nested_property": "some nested property",
        "library": "some library",
        "user_property_1": "some user property value 1"
  },
},

Event body editor

This section is a Freemarker template that lets you construct the payload sent to your destination. The template in the screenshot can correspond to the example payload structure, depending on how the user configures their sync and the Customize user properties mapping section.

• Input: This object includes the forwarded event and its fields. Amplitude enriches the object with the user's other events and user properties. These fields aren't guaranteed and depend on how each user instruments events. Amplitude suggests keeping input field usage to a minimum and using common fields such as user_id, event_type, and event_time.
• Parameters: A key-value pair where the key is a Parameter Name defined in the Create Parameters section. The value corresponds to the value that the user provided when setting up their sync.
• MappedProperties: A key-value pair of event, user, or group properties that the customer might want to forward to your destination. For example, a customer may track an email: example@example.com property and may want to forward that property to your platform. Amplitude forwards these properties only if the user selects them in the UI under Specify event properties to send.
• MappedFields: A key-value pair where the key is a Destination Property Name specified in the Customize user properties mapping section. The value corresponds to the value of an Amplitude property that the user selects in the UI under the Mappings tab. For example, you may have specified external_id as a field, and the user may have selected the Amplitude property email: example@example.com in the UI. Then MappedFields is a key-value pair: {external_id: example@example.com}.

Preview and test

1. Before you submit your configuration for review, test the mock payload that you expect to receive from Amplitude on the Testing tab. The Destination Preview form matches what users of the integration view. Enter the parameters you defined in this form to use as test values. You can also configure mapped properties and filters on this form.

2. Click Test Connection to open the testing modal. Test Connection appears after you enter all required parameters. This lets you customize your payload. Click Send Test Event. Any responses from the endpoint you specified appear on the right.

3. If errors appear, check the parameters table to make sure all declared parameters have corresponding uses.

   • DECLARED: All declared parameters in the Create Parameters section.
   • USED: All parameters used in the URL, headers, and event body.

Release internally

To test in your org, click Release Internally. This enables anyone within your org to use the integration you defined. Allow up to 5 minutes for changes to take effect.

Submit the integration

After you finish testing, click Submit to submit your integration to the Amplitude team. The review process takes about one week. When Amplitude approves your integration, Amplitude notifies you by email and your integration tile appears in the Destination section of Amplitude.