Segment integration

What it does

The Segment integration lets your agency forward events into a client's Segment source from any TaskJuice workflow. Connect a client's source once and your workflows can record what users do (track), associate users with their traits (identify), group those users into accounts or organizations (group), record page views (page), merge identities when an anonymous session becomes a known user (alias), and ship up to 500 KB of mixed events in a single batch. Because Segment is a source rather than a destination, this integration is action-only: there are no webhooks to subscribe to from Segment itself, and any downstream destinations the client connects in their Segment workspace receive every event you send through TaskJuice.

Connect a Segment account

1. Open your workspace in TaskJuice and navigate to Connections.
2. Choose Segment and click Connect.
3. In a new tab, open the client's Segment workspace, go to Connections, Sources, and choose the source you want to forward events into. If the source does not exist yet, create an HTTP API source first.
4. Open the source's Settings, API Keys panel and copy the Write Key.
5. Paste the Write Key into TaskJuice. Leave the HTTP Basic password field blank, the Segment HTTP Tracking API uses the Write Key as the username with no password.
6. Save the connection.

To rotate the Write Key later, regenerate it in the source's API Keys panel, update the connection in TaskJuice, and the next run will pick it up. Revoking the old key in Segment takes effect immediately.

Triggers

Segment does not push event webhooks because Segment is itself the event source. Workflows react to events from the originating system (the CRM, web app, billing platform) and forward them into Segment using the actions below. If you need to react to events that have already entered Segment, configure a Segment destination that posts back to a TaskJuice Webhook trigger.

Actions

• segment/track-event records an action a user took, with optional properties, context, timestamp, and a message ID for idempotency.
• segment/identify-user associates a user with their traits (email, name, plan, lifetime value, and so on).
• segment/group-user associates a user with a group such as an account, organization, or team.
• segment/page-view records a page view with optional name, category, and properties.
• segment/alias-user merges two identities, typically used to attach an anonymous session to a known user once they sign in.
• segment/batch-send ships up to 500 KB of mixed track, identify, group, page, screen, and alias events in one request through /v1/batch.

Known limitations

• The HTTP Tracking API enforces a 32 KB ceiling on single calls and a 500 KB ceiling on /v1/batch payloads. Workflows that need to ship more events should split the batch upstream.
• Authentication uses HTTP Basic with the Write Key as the username and a blank password. The bundle stores a documentation-only password field that must be left empty, populating it does not change the request Segment receives.
• A successful 200 response from the Tracking API means Segment accepted the payload, not that downstream destinations have processed it. Delivery to Mixpanel, Amplitude, or warehouse destinations happens asynchronously inside Segment.
• The Tracking API does not return resource IDs. Workflows that need the canonical Segment event ID should generate a messageId client-side and reference that ID downstream.
• Segment does not push event webhooks, so any "react to a Segment event" workflow must be driven from the originating source or from a Segment destination configured to post to a TaskJuice Webhook trigger.