Connect Segment¶

Segment is a customer data platform (CDP): instead of Squoosh reading from a reporting API, your Segment workspace pushes events to Squoosh through a destination you configure. This page covers what that connection does today and how to set it up.

What the connection does¶

1. In the sidebar, click Integrations.
2. In the Segment row, click Connect.
3. Squoosh generates a unique ingest URL and a shared secret, and shows both to you once.
4. Copy both immediately. The secret is not stored in a way Squoosh can show you again. If you lose it, disconnect and reconnect to generate a new one.

The row shows Endpoint ready once the connection is created, and Receiving events after Segment successfully sends its first event.

Add the destination in Segment¶

In your Segment workspace, add a Webhooks (Actions) destination on the source you want to send from. (Segment's older, classic Webhooks destination is in maintenance mode. Use Webhooks (Actions) for any new setup.)

1. In Segment, go to your source's Destinations and add a new Webhooks (Actions) destination.
2. On the destination's Send action, set:
3. URL: the ingest URL Squoosh gave you (https://<your-squoosh-domain>/api/integrations/segment/ingest?connection=<your connection id>).
4. Method: POST (required).
5. Headers: add x-squoosh-segment-secret: <the shared secret>. Segment accepts ASCII header values; paste the generated secret unchanged.
6. Enable Batching?: set off. Squoosh does not aggregate events yet, so batching adds nothing, and one event per request keeps you well under the 1 MiB whole-request limit described below.
7. Enable the destination and its configured mapping, then send a test event from Segment.

A successful test event gets a 202 Accepted response. For a 401 response, check the secret, the connection id in the ingest URL, and whether the connection was disconnected in Squoosh.

Alternative: Segment's own Shared Secret signing¶

You can use Segment's own signing mechanism instead of the custom header: in Settings → Advanced Settings, set Shared Secret to the secret Squoosh gave you. Segment signs the JSON with HMAC-SHA1 and sends a hex digest in X-Signature. No Headers mapping is needed. Squoosh verifies the signature Segment sends: the first event of a batch, or the whole body of an unbatched request. It works with batching on or off, so a signature failure points at the secret or the connection, not at the batching setting. See Segment's signing and batching documentation.

A batch signature proves that its first event came from Segment; it does not cover the other events in the batch. Squoosh does not store or count events at this stage, so nothing depends on the rest of the batch. An existing destination with a valid custom header still authenticates when its signature does not match. The custom header does not bypass the size limit either: a batch above 1 MiB is rejected whole, which is why batching off is the recommended setup.

Request size and delivery failures¶

Squoosh's 1 MiB (1,048,576 bytes) limit applies to the entire request body, including all events in a batch. Segment's batching limits can produce requests above this limit. A custom header does not make a large batch acceptable. If a request exceeds the limit, Squoosh returns 413 and accepts none of it.

Responses 400, 401, 405 and 413 are not automatically retried by Segment. Correct the configuration and send a new test event; do not wait for retries to repair it. Segment retries 408, 423, 429 and 5xx responses except 501, subject to its delivery retry window. See the official status classification and destination retry policy.

Segment's Webhooks (Actions) destination has no Basic-auth option, so set your destination up with one of the two mechanisms above. For back-compat only, the endpoint also still accepts the shared secret presented as HTTP Basic credentials, in either the username or the password position, because earlier setup copy told customers to configure it that way. If you have a destination doing that it keeps working, but don't build a new one on it.

What happens in the surface stage¶

Each incoming request is authenticated and checked against the size and rate limits before it is acknowledged. Squoosh does not store or aggregate the event payload at this stage. There's no event history to browse and no effect on your AI shopper pool yet. When Segment aggregation ships, this page will describe what it calibrates and how.

Change or remove the connection¶

In the Segment row:

• Click Disconnect to remove the connection. Squoosh stops accepting events at the ingest URL (any further requests get 401), and the shared secret is invalidated.
• Reconnecting generates a new ingest URL and a new shared secret. Update your Segment destination with both.

Troubleshooting¶

Related¶

• Google Analytics and Shopify: calibration sources that work today.
• AI shoppers: how a calibrated pool behaves once a source is grounded.