---
title: Segment
---
# Segment

Svix can deliver webhooks directly to [Segment](https://segment.com), without your customers having to set up any listener endpoint or write any glue code. Each batch of webhooks is sent to Segment's [HTTP Tracking API `/v1/batch` endpoint](https://segment.com/docs/connections/sources/catalog/libraries/server/http-api#batch).

When **Advanced Destinations** are [enabled](/advanced-destinations#enabling-advanced-destinations), your customers will see the option to use a Segment destination in the [App Portal](/app-portal).

![Segment Destination Create](/img/advanced-destinations/segment-create.png)

They will be able to configure the connection right in the App Portal:

- `host` — the Segment ingestion host. This is `https://api.segment.io` for US workspaces, `https://events.eu1.segmentapis.com` for EU workspaces, or a custom domain.
- `writeKey` — the Segment source write key. Svix sends it using HTTP Basic auth, with the write key as the username and an empty password.

<Callout type="info">
Segment destinations require a transformation. The transformation is what builds the Segment batch, and each entry in the batch must be a valid Segment call — one of `identify`, `group`, `track`, `page`, or `screen`.
</Callout>

# Transformations

Each webhook is mapped to a Segment call. A transformation returns the `batch` of calls to send, plus an optional `context` applied to every call.

```JavaScript
/**
 * @param input - The input object
 * @param input.events - The array of webhooks in the batch. The number of webhooks in the batch is capped by the destination's batch size.
 * @param input.events[].payload - The message payload (string or JSON).
 * @param input.events[].eventType - The message event type (string).
 * @param input.events[].createdAt - The ISO 8601 timestamp the webhook was received at (string).
 *
 * @returns Object containing the batch of events sent to Segment's /v1/batch endpoint.
 * @returns returns.context - An optional dictionary of extra information, applied to every event in the batch.
 *                            For acceptable context fields, see
 *                            https://segment.com/docs/connections/spec/common#context
 * @returns returns.batch - An array of events sent in the batch. Each event must be one of
 *                          "identify", "group", "track", "page", or "screen", and is sent verbatim
 *                          to Segment's /v1/batch endpoint. See
 *                          https://segment.com/docs/connections/sources/catalog/libraries/server/http-api#batch
 */
function handler(input) {
  // An optional dictionary of extra information, applied to every event in the batch.
  const context = {};

  const batch = input.events.map((event) => ({
    // One of "identify", "group", "track", "page", or "screen".
    type: "track",
    event: event.eventType,
    timestamp: event.createdAt,
    ...event.payload,
  }));

  return { context, batch };
}
```

`input.events` is the list of webhooks received by the destination, processed in batches.

The transformation builds a Segment batch. Each entry is one of Segment's call types (the default is a [`track`](https://segment.com/docs/connections/spec/track) call) and is forwarded to Segment verbatim, so you have full control over the fields on each call. The optional `context` object is applied to every event in the batch.

For example, if the destination receives the following messages:

```json
{
  "eventType": "order.completed",
  "payload": "{\"userId\": \"usr_123\", \"total\": 42.0}"
}
```

```json
{
  "eventType": "order.completed",
  "payload": "{\"userId\": \"usr_456\", \"total\": 9.99}"
}
```

The default transformation would result in the following request being made to Segment's [`/v1/batch` endpoint](https://segment.com/docs/connections/sources/catalog/libraries/server/http-api#batch):

```json
{
  "batch": [
    {
      "type": "track",
      "event": "order.completed",
      "timestamp": "2025-11-03T14:20:16.466Z",
      "userId": "usr_123",
      "total": 42.0
    },
    {
      "type": "track",
      "event": "order.completed",
      "timestamp": "2025-11-03T14:20:16.526Z",
      "userId": "usr_456",
      "total": 9.99
    }
  ]
}
```

These events would subsequently be visible in your Project's dashboard.

![segment-dashboard](/img/stream/segment-dashboard.png)