Segment integration

What it does

The Segment integration works in both directions. Your workflows can send events into a client's Segment source: what users do (track), who they are (identify), which account they belong to (group), page and screen views, and identity merges (alias), one at a time or up to 500 KB in a single batch. Every destination the client has connected in Segment then receives those events.

In the other direction, Segment can send the events it collects to TaskJuice as they happen, so a workflow starts the moment a user completes an order, signs up, or joins an account.

Connect a Segment account

1. In the client's Segment workspace, go to Connections, Sources, and choose the source you want to send events into. If it does not exist yet, create an HTTP API source first.
2. Open the source's Settings, API Keys panel and copy the Write Key.
3. In TaskJuice, go to Connections, choose Segment, and paste the Write Key. Leave the HTTP Basic password field blank: Segment uses the Write Key as the username with no password.
4. If you plan to use Segment triggers, also fill in Webhook shared secret (see below). Save the connection at the account level so the secret applies to every workspace.

To rotate the Write Key later, regenerate it in the source's API Keys panel and update the connection in TaskJuice. The next run uses the new key.

Triggers

Each trigger fires on one Segment call type:

• segment/track-event-received (Track Event Received) fires on a track call, such as Order Completed. Set Event name to fire for one event only.
• segment/identify-received (User Identified) fires on an identify call, with the user's traits.
• segment/page-received (Page Viewed) fires on a page call from a website.
• segment/screen-received (Screen Viewed) fires on a screen call from a mobile app.
• segment/group-received (User Added to Group) fires on a group call, with the account's traits.
• segment/alias-received (Identities Merged) fires on an alias call.

The trigger output is the Segment event itself: type, messageId, userId, anonymousId, timestamp, context, plus event and properties for track calls, traits for identify and group calls, and name for page and screen calls.

Send events from Segment to TaskJuice

Segment has no Write Key API for creating destinations, so you set this up once per Segment source by hand.

1. Publish a workflow with a Segment trigger and copy its TaskJuice webhook URL.
2. In Segment, open the source and add a Webhooks (Actions) destination.
3. In the destination's Settings, enter a long random value in Shared Secret and save.
4. Add a Send mapping. Set URL to the TaskJuice webhook URL and Method to POST. Leave Data at its default, which sends the whole event, and leave Enable Batching off.
5. Choose which events the mapping sends, for example all track and identify calls, and enable the destination.
6. In TaskJuice, edit the Segment connection and paste the same value into Webhook shared secret.

Segment signs every request with that secret, and TaskJuice refuses any request it cannot verify. If Segment retries a delivery, TaskJuice recognizes the repeated messageId and runs the workflow only once.

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, such as email, name, and plan.
• segment/group-user associates a user with a group such as an account, organization, or team.
• segment/page-view records a website page view with an optional name, category, and properties.
• segment/screen-view records a mobile app screen view with an optional name and properties.
• segment/alias-user merges two identities, typically to attach an anonymous session to a known user once they sign in.
• segment/batch-send sends up to 500 KB of mixed track, identify, group, page, screen, and alias events in one request.
• segment/tracking-api-call sends any Tracking API call with a JSON body you build yourself, for fields the other actions do not expose.

Known limitations

• Actions send to Segment's default Oregon endpoint (api.segment.io). Workspaces in Segment's Dublin region (events.eu1.segmentapis.com) are not supported yet: Segment accepts the request but the events do not appear in the workspace.
• The Tracking API limits single calls to 32 KB and batches to 500 KB. Split larger batches upstream.
• A 200 response means Segment accepted the payload, not that downstream destinations have processed it. Delivery to the client's destinations happens later inside Segment.
• The Tracking API does not return event IDs. To reference an event later, set your own messageId.
• Triggers need Enable Batching off on the Send mapping. On a batched request Segment signs only the first event, so TaskJuice cannot verify it and refuses the delivery.
• Your TaskJuice account verifies Segment deliveries with one shared secret, so use the same shared secret on every client's destination. A Segment event reaches every published Segment trigger of its call type in your account, across client workspaces. If you serve several clients from one account, narrow each Track Event Received trigger with Event name, or give each client's events distinct event names.
• Creating sources and destinations needs a Segment Public API token, which is only available on Team and Business plans and is a different credential from the Write Key. The integration does not manage sources or destinations.