Gainsight EventStream Connector

Last updated
Save as PDF

This article explains how to create a Gainsight EventStream connection and map event-based fields.

Overview

The Gainsight EventStream connector enables external systems, such as SAP Sales Cloud or HubSpot, to push event-based data into Gainsight in real time.
Unlike traditional connectors that pull data from external systems, this connector supports real-time, event-driven integration.

Key Capabilities

Event-Driven Integration: Enables external platforms to send event payloads (for example, record creation, updates, or changes) to Gainsight.
Custom Event Templates: Supports defining and managing custom event types and mappings.
Multi-Object Upsert: Allows a single event to upsert data into multiple Gainsight objects simultaneously.

Supported Destination Objects

The Gainsight EventStream connector supports the following target objects in Gainsight:

Company
Person
Company Person
Low-volume custom objects
Opportunity

Note: Admins must ensure the SSO is active to use EventStream Connector.

Create a Connection

The first step to configure the Gainsight EventStream connector is to generate OAuth credentials.

To generate the credentials:

Navigate to Administration > Connectors 2.0 > Connections.
Click Create Connection. The Create Connection dialog appears.
From the Connector dropdown list, select Gainsight EventStream Connector.
In the Name of the connection field, enter a name for the connection.
Click Generate OAuth Credentials. This auto-populates all the required credential fields.

Create Gainsight EventStream Connector with OAuth API credentials and connection details form.

After credentials are generated, you must copy them from Gainsight and configure them in the source system’s webhook or workflow setup.

This setup ensures that the source system can authenticate using OAuth, generate an access token, and push event data (in JSON format) to Gainsight’s Event URL in real time.

Context Menu

To view the context menu for any connector, click the three vertical dots icon to view the following options:

Edit Connection: Modify the Gainsight EventStream connection details.
Delete Connection: Delete the connection permanently.

Manage Events

After the configuration in the source system is completed, you can manage events from the Connectors page in Gainsight.

To manage events:

Click Manage Events. The Manage Events page appears.
From Add Event Mapping, select either of the following options:
- Use Template: Use pre-built templates for mapping.
- Create Custom: Define a custom event mapping based on a unique key-value pair present in the event payload emitted by the source system. In the JSON payload, there is typically one key that uniquely identifies the event type. Gainsight expects admins to specify that key and its corresponding value to help the system identify which mapping to apply when events are received.

Event management screen showing no existing mappings with option to add event mapping.

Pre-Built Templates

You can use the out-of-the-box templates to auto-map the event types to Gainsight fields.

To use the pre-built templates:

From Add Event Mapping, select Use Templates. The Event Mapping Template slide-out panel appears.
From the Select External Event System dropdown, select the available template. A list of all available event types appears.
Select the Event Types.
Click Save.

Event mapping template showing SAP Sales Cloud events list with auto-mapping options.

The list of mapped events starts appearing once the template is saved. You can now edit the already-mapped fields to more Gainsight objects if required.

Manage events page showing mapped SAP Sales Cloud events linked to Gainsight objects.

Custom Templates

You can build custom templates to map the event types to Gainsight fields. To add the custom templates:

From Add Event Mapping, select Create Custom. The Create Custom Event Mapping dialog appears.
In the Event Key field, enter the key from your event payload that uniquely identifies the type of event. Use dot notation (for example, event.type) if the key is nested.
In the Event Type field, enter the value to match incoming events against the key you defined above. For example: AccountCreated, ContactCreated, or EmailDeleted.
Click Create Mapping.

Create custom event mapping window with fields for event key and event type setup.

Once the event type is created, the next step is to map the fields. Edit the event type to map the fields to Gainsight objects.

Manage events page showing unmapped custom event with option to edit or delete mapping.

Add Fields to Map Events

The Edit Mapping slide-out panel helps you add the fields to map to the Gainsight object.

To add the fields:

In the Edit Mapping slide-out panel, click Add Fields.
From the Gainsight Object dropdown, select the target object.
Note: You can select multiple objects to map.
Click + Add Field
In Source Fields, enter the field from the source to be mapped.
From the Target Fields dropdown, select the field to be mapped.
Note: It is mandatory to select an Identifier from the list of fields added.
Click Save. The event fields are now mapped to the Gainsight fields.

Manage events page showing updated custom event mapped to Active Object in Gainsight.