Segment

Svix can deliver webhooks directly to Segment , 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.

When Advanced Destinations are enabled, your customers will see the option to use a Segment destination in the App Portal.

Segment Destination Create

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.

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.

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.


/**
 * @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 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:


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


{
  "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:


{
  "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