> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conversion.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sending Events from Segment

> Forward Segment track events to Conversion so you can segment contacts and trigger workflows off product usage data.

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](/product-docs/audiences/overview) and trigger [event-based workflows](/product-docs/workflows/triggers/event-based).

The integration uses Segment's built-in **Webhooks (Actions)** destination to call the Conversion [Track Event](/api-reference/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](/product-docs/workspace-settings/integrations/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

<Steps>
  <Step title="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**.
  </Step>

  <Step title="Add a mapping">
    Open the new **Conversion** destination, go to the **Mappings** tab, and click **New mapping**. Choose the **Send** action.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Configure the request">
    Fill in the mapping fields as follows:

    | Field       | Value                                         |
    | :---------- | :-------------------------------------------- |
    | **URL**     | `https://pub-api.conversion.ai/api/v2/events` |
    | **Method**  | `POST`                                        |
    | **Headers** | `X-API-Key` set to your Conversion API key    |

    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.

    | Segment value     | Conversion key             |
    | :---------------- | :------------------------- |
    | `email`           | `email`                    |
    | `event`           | `event`                    |
    | `userId`          | `userId`                   |
    | `$event`          | `data`                     |
    | `True` (constant) | `createContact` (optional) |

    <Note>
      `$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.
    </Note>

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="Save and enable the mapping">
    Save the mapping and make sure both the mapping and the destination are enabled.
  </Step>
</Steps>

## 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](/api-reference/track-event) reference for the full request and response format, including error codes.