Skip to main content
Segment can forward the events it already collects from your product to Conversion. Once connected, every event you choose to send lands on the matching contact as a custom event, where you can use it to build audiences and trigger event-based workflows. The integration uses Segment’s built-in Webhooks (Actions) destination to call the Conversion Track Event endpoint.

​
Before you begin

Make sure you have:
  • A Conversion API key. Generate one from Settings → API Keys in the Conversion dashboard. See API for details.
  • A Segment workspace with a source that is already collecting the track events you want to forward.
  • Permission to add destinations in that Segment workspace.

​
Connect Segment to Conversion

1

Create the destination

In Segment, go to Connections → Destinations and click Add destination. Search for Webhooks (Actions), select it, and connect it to the source you want to forward events from. Name the destination Conversion.
2

Add a mapping

Open the new Conversion destination, go to the Mappings tab, and click New mapping. Choose the Send action.
3

Select the events to send

Under the trigger conditions, choose which Event Names should be forwarded to Conversion. Only the events you select here are sent, so start with the handful you plan to segment or trigger on.
4

Configure the request

Fill in the mapping fields as follows:For the Data field, choose Edit Object and add these key/value pairs. The left column is the Segment event property, and the right column is the key Conversion expects.
$event is the full Segment event payload. Mapping it to data attaches every property of the event to the custom event in Conversion, so you can reference them in audience filters and workflows.
To create a new contact when no existing contact matches the userId or email on the event, add the createContact pair with the constant value True. Creating a contact requires an email on the event. Leave this out if you only want events recorded against contacts that already exist.
5

Save and enable the mapping

Save the mapping and make sure both the mapping and the destination are enabled.

​
Test the connection

Use Send test event on the mapping in Segment, or trigger one of the selected events from your product. The event appears on the matching contact in Conversion within a few minutes.

​
How events are matched to contacts

Conversion matches each event to a contact using the identifiers on the request:
  • If userId matches an existing contact, that contact is used.
  • Otherwise, Conversion falls back to email.
  • If neither matches and createContact is not set, the event is rejected and no contact is created.
At least one of userId or email must be present on every event. See the Track Event reference for the full request and response format, including error codes.