> ## 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 Hightouch

> Send events from Hightouch to Conversion to build audiences and trigger workflows.

Send events such as `trial_started` or `plan_upgraded` from your warehouse to Conversion. Each event is recorded on a matching contact and can be used in [audiences](/product-docs/audiences/overview) and [event-based workflows](/product-docs/workflows/triggers/event-based).

On each scheduled sync, Hightouch sends new event rows to the Conversion [Track Event](/api-reference/track-event) endpoint, with one HTTP request per event.

<Note>
  To send live events from Hightouch to Conversion, contact our team for setup guidance.
</Note>

## Before you begin

Make sure you have:

* **A Conversion HTTP destination.** Follow the connection steps in [Syncing Contacts](/product-docs/sync/hightouch/syncing-contacts#connect-hightouch-to-conversion).
* **A Hightouch model** with one row per event, including a unique event ID, contact email, event name, and occurrence time.

Use the event ID as the model's primary key. Each occurrence needs its own ID, even when the same contact performs the same action again.

## Configure the event sync

<Steps>
  <Step title="Create a sync">
    Create a sync using your event model and the **Conversion** destination.
  </Step>

  <Step title="Configure the request">
    Enable **Rows added** only. Leave **Rows changed** and **Rows removed** disabled.

    | Setting          | Value                                        |
    | :--------------- | :------------------------------------------- |
    | Method           | `POST`                                       |
    | Endpoint path    | `/api/v2/events`                             |
    | Rows per request | A single row                                 |
    | Payload          | JSON, using multiple columns from your model |
  </Step>

  <Step title="Map event fields">
    Map your model's columns to these Conversion fields:

    | Example source column | Conversion key | What to send                                               |
    | :-------------------- | :------------- | :--------------------------------------------------------- |
    | `email`               | `email`        | Contact's email                                            |
    | `event_name`          | `event`        | Event name                                                 |
    | `event_id`            | `eventId`      | Unique event ID, as a string                               |
    | `occurred_at`         | `timestamp`    | Original event time in ISO 8601 format, including timezone |
    | `properties`          | `data`         | Optional object containing event details                   |

    For example, your mappings could produce:

    ```json theme={null}
    {
      "email": "jane@example.com",
      "event": "plan_upgraded",
      "eventId": "billing:upgrade:12345",
      "timestamp": "2026-09-01T14:30:00Z",
      "data": {
        "plan": "pro",
        "annual": true
      }
    }
    ```

    Hightouch fills in the values automatically for each row. Map `data` from an object column, or build it from separate columns using Hightouch's [inline mapper](https://hightouch.com/docs/syncs/mapping-data#inline-mapping), if enabled.

    <Tip>
      To create a contact when its email is not found, map the boolean constant `true` to `createContact`. Otherwise, make sure your contacts have synced successfully before sending their events.
    </Tip>
  </Step>

  <Step title="Choose the initial history and schedule">
    Choose whether the first run should send existing event rows or skip them and send future additions. Historical events can also trigger workflows.

    Set the sync schedule and enable retries for failed rows. Keep event rows available in your source until they have been delivered successfully.
  </Step>
</Steps>

## Test the connection

Send one test event and confirm its name, timestamp, and properties on the matching contact in Conversion. Send it again with the same `eventId` to check that Conversion reports `duplicate: true` without recording it twice.

## Event IDs and timestamps

Keep each `eventId` unique across your workspace, and reuse it when retrying that event. Conversion ignores duplicate IDs. Without an ID, each request creates another event.

Send the original `timestamp` to preserve when the event happened. If omitted, Conversion uses the time it receives the event. Workflows can react once the event arrives in Conversion.

## How events are matched to contacts

This setup matches contacts by email. You can also identify a contact with `userId`; if both are sent, Conversion tries `userId` first, then email. Events for unknown contacts are rejected unless `createContact` is enabled and an email is provided.

Event properties do not update contact profile fields. Use a [contact sync](/product-docs/sync/hightouch/syncing-contacts) for those updates. See [Track Event](/api-reference/track-event) for the full request options.