Segment integration

Segment is a customer data platform (CDP) that lets you collect, unify, and route customer data. This integration can send identify, track, page, group, alias, screen, and reset events either from your backend (API Endpoints, server-side) or from the interface (browser, when a user does something in the app). Backend calls use Segment’s HTTP API and a Node.js Write Key; interface calls use Segment’s browser library and a JavaScript Write Key.

Use cases

• Identify users and attach traits after sign-up or login
• Track key product events for analytics and growth funnels
• Group users to accounts/organizations for B2B analytics
• Record server-side page events for consistency across channels

Setup

1. In Segment, create two sources (or use one workspace with both types):
   • A Node.js source — for backend (API Endpoint) workflows. Copy its Write Key → in WeWeb this is the Backend Write Key.
   • A JavaScript source — for interface (browser) workflows. Copy its Write Key → in WeWeb this is the Frontend Write Key.
2. In WeWeb, open the Segment integration and add a connection. For each environment (Editor, Staging, Production), set:
   • Backend Write Key — from the Node.js source (required for backend actions).
   • Frontend Write Key — from the JavaScript source (required for interface actions).
3. Test backend: run a minimal Track from an API Endpoint with event and userId or anonymousId. Test interface: add a Track event step in an Interface workflow (e.g. on button click) and trigger it.
4. If events don’t appear in Segment, check source filters, workspace permissions, and the environment you’re sending from.

Common pitfalls (setup & usage)

Wrong source type selected

The most common setup mistake is selecting the wrong source type in Segment.

• For backend workflows, create a Node.js source and use its Write Key as the Backend Write Key in WeWeb.
• For interface workflows, create a JavaScript source and use its Write Key as the Frontend Write Key in WeWeb.

If you selected the wrong type, create a new source with the correct type and update the key in your WeWeb connection.

Missing userId or anonymousId

Segment requires at least one of userId or anonymousId on events. Include one consistently across calls.

Invalid traits/properties shape

Traits and properties must be JSON objects. Arrays or primitives at the root can be rejected.

Timestamp format

Provide an ISO 8601 string for timestamp if you set it; otherwise Segment sets it automatically.

Interface (frontend) actions

The Segment actions (Identify, Track, Page, Group, Alias, Screen, and Reset) are available in Interface workflows. When you use them there, they run in the user's browser via Segment’s browser library and your Frontend Write Key (JavaScript source). No request goes through your WeWeb backend for these calls.

• Identify user — Set the user’s identity in the browser (the action uses an ID field) and optional Traits. Use after login to link activity to a known user.
• Track event — Send an Event name and optional Properties. Fires from the browser when the step runs (e.g. on button click, form submit).
• Track page view — Send a Page Name, optional Category and Properties. Use when the user navigates to a page (e.g. in a "Page loaded" workflow).
• Group user — Associate the user with a Group ID and optional Traits (e.g. account or organization). Use when you know the user's org/account.
• Alias user — Merge identities so Segment ties past anonymous activity to the signed-in user. In Interface workflows, Segment can use the current browser identity as the “previous” identity.
• Track screen view — Send a Screen Name, optional Category and Properties. Common in mobile or app-like flows for "screen" views.
• Reset identity — Clears the current user identity and generates a new anonymous ID. Use in a logout workflow so subsequent activity is not tied to the previous user.

Interface actions use the Frontend Write Key from your Segment connection. Identity is managed in the browser by Segment; context (like page URL and referrer) is added automatically where applicable.

When to use frontend vs backend actions

Use case	Prefer	Why
User clicks a button, submits a form, or views a page in the app	Interface (frontend)	Event happens in the browser; frontend tracking captures it immediately with automatic context (URL, referrer, device). No extra API call to your backend.
Page views, screen views, or in-app navigation	Interface (frontend)	Fires when the user lands on a page/screen; Analytics.js can add context automatically.
Identify or alias after login (in the app)	Interface (frontend)	The logged-in user is in the browser; frontend identify/alias keeps the same device/session identity.
Logout (clear identity, new anonymous ID)	Interface (frontend)	Reset Identity runs in the browser and clears the current Segment identity there.
Server-side events: order confirmed, subscription renewed, webhook received	Backend	The event is triggered by your server or an external system; only the backend can send it. Keeps a single source of truth.
Same event must be sent from multiple channels (e.g. app + email + API)	Backend	One API Endpoint can fire Segment track/identify so all channels see the same event with consistent timestamps and context.
Sensitive or high-value events you don't want exposed in the client	Backend	Backend calls use your Node.js key and don't rely on the browser; logic and data stay server-side.
Batch or historical uploads, ETL, or scripts	Backend	Use API Endpoints or server workflows to send identify/track/group with full control over IDs and timestamps.

In short: use interface (frontend) for user-driven, in-browser behavior (clicks, page views, identify on login, reset on logout). Use backend for server-authoritative or multi-channel events, or when the trigger is not in the browser.

All Actions

This integration provides actions that can run in backend workflows (API Endpoints) or interface workflows (browser). Backend actions use the Node.js Write Key and Segment’s HTTP API; interface actions use the JavaScript Write Key and Analytics.js (see Interface (frontend) actions). The table below lists the four actions available for backend (HTTP API); Identify, Track, Page, Group, plus Alias User, Track Screen View, and Reset Identity are also available in interface workflows.

Action	Description
Identify	Tie a user to traits; create/update a user profile
Track	Record a user action (event name + properties)
Page	Record a page call (name/category/properties)
Group	Associate a user with a group (e.g., account or org)

Action details

Identify

Attach traits to a user profile.

Inputs

Display Key	Example Input	Description	Restrictions
User ID Optional	"user_123"	Stable user identifier	Required if no Anonymous ID
Anonymous ID Optional	"anon_abc"	Device/session identifier	Required if no User ID
Traits Optional	{"plan":"pro","email":"a@b.com"}	User traits	JSON object
Timestamp Optional	"2025-11-15T10:23:00Z"	Event timestamp	ISO 8601
Context Optional	{"ip":"1.2.3.4"}	Context info (ip, userAgent, …)	JSON object
Integrations Optional	{"All":true}	Destination toggles	JSON object
Message ID Optional	"m-123"	Idempotency key	String

Example output

{ "success": true }

Documentation of API endpoint that powers action: Segment HTTP API – Identify (POST /v1/identify)

Track

Record a user action.

Inputs

Display Key	Example Input	Description	Restrictions
User ID Optional	"user_123"	Stable user identifier	Required if no Anonymous ID
Anonymous ID Optional	"anon_abc"	Device/session identifier	Required if no User ID
Event	"Item Purchased"	Event name	Required
Properties Optional	{"sku":"123","price":10}	Event properties	JSON object
Timestamp Optional	"2025-11-15T10:23:00Z"	Event timestamp	ISO 8601
Context Optional	{"ip":"1.2.3.4"}	Context info	JSON object
Integrations Optional	{"All":true}	Destination toggles	JSON object
Message ID Optional	"m-456"	Idempotency key	String

Example output

{ "success": true }

Documentation of API endpoint that powers action: Segment HTTP API – Track (POST /v1/track)

Page

Record a page call for server-side parity.

Inputs

Display Key	Example Input	Description	Restrictions
User ID Optional	"user_123"	Stable user identifier	Required if no Anonymous ID
Anonymous ID Optional	"anon_abc"	Device/session identifier	Required if no User ID
Name Optional	"Pricing"	Page name	String
Category Optional	"Marketing"	Page category	String
Properties Optional	{"path":"/pricing"}	Page properties	JSON object
Timestamp Optional	"2025-11-15T10:23:00Z"	Event timestamp	ISO 8601
Context Optional	{"ip":"1.2.3.4"}	Context info	JSON object
Integrations Optional	{"All":true}	Destination toggles	JSON object
Message ID Optional	"m-789"	Idempotency key	String

Example output

{ "success": true }

Documentation of API endpoint that powers action: Segment HTTP API – Page (POST /v1/page)

Group

Associate a user with a group (e.g., organization or account).

Inputs

Display Key	Example Input	Description	Restrictions
User ID Optional	"user_123"	Stable user identifier	Required if no Anonymous ID
Anonymous ID Optional	"anon_abc"	Device/session identifier	Required if no User ID
Group ID	"org_456"	Organization/account identifier	Required
Traits Optional	{"plan":"enterprise"}	Group traits	JSON object
Timestamp Optional	"2025-11-15T10:23:00Z"	Event timestamp	ISO 8601
Context Optional	{"ip":"1.2.3.4"}	Context info	JSON object
Integrations Optional	{"All":true}	Destination toggles	JSON object
Message ID Optional	"m-101"	Idempotency key	String

Example output

{ "success": true }

Documentation of API endpoint that powers action: Segment HTTP API – Group (POST /v1/group)

Error handling

Error code and type	Reason
401 Unauthorized	Invalid or missing Write Key.
400 Bad Request	Invalid payload shape or required fields missing.
403 Forbidden	Write Key lacks access or workspace restrictions.
429 Too Many Requests	Rate limited; backoff and retry.
500 Internal Server Error	Provider-side error; retry with backoff.

FAQs

What source type should I select in Segment?

You must select Node.js as the source type when creating your Segment source. This integration uses Segment's HTTP API which is compatible with the Node.js source type. Other source types will not work correctly.

Do I need both userId and anonymousId?

No. Provide at least one. Use userId for logged-in users and anonymousId for pre-login activity.

Can I control which destinations receive an event?

Yes, pass an integrations object (e.g., {"All": true, "Amplitude": false}) to enable/disable destinations per call.