Skip to content

Updating visuals

If you see any images containing outdated UI, please bear with us.

We are updating all content as quickly as possible to mirror our new UI.

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. Sign in to Segment.
  2. Go to Sources and click Add source.
  3. Search for Node.js, select it, and create the source.
  4. Copy the write key — this becomes your Backend Write Key in WeWeb.
  5. Create a second source: click Add source, choose JavaScript, name it if needed, and create it.
  6. Open the JavaScript source Settings → API Keys and copy the write key — this becomes your Frontend Write Key in WeWeb.
  7. 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)
  8. Test backend: run a minimal Track from an API Endpoint with event and userId or anonymousId.
  9. Test interface: add a Track event step in an Interface workflow and trigger it.
  10. If events do not appear in Segment, check source filters, workspace permissions, and the environment you are 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 casePreferWhy
User clicks a button, submits a form, or views a page in the appInterface (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 navigationInterface (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 receivedBackendThe 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)BackendOne 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 clientBackendBackend 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 scriptsBackendUse 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 six actions available for backend (HTTP API). They are also available in interface workflows, along with Reset Identity, which only runs in the browser.

ActionDescription
Identify UserTie a user to traits; create/update a user profile
Track EventRecord a user action (event name + properties)
Track Page ViewRecord a page call (name/category/properties)
Group UserAssociate a user with a group (e.g., account or org)
Alias UserMerge a previous identity into a new one (e.g., anonymous ID into user ID)
Track Screen ViewRecord a screen view (name/category/properties)

In each action except Alias User, choose User or Anonymous first: the action then shows User ID or Anonymous ID. In backend workflows, the field you see is required.

Action details ​

Identify User ​

Attach traits to a user profile.

Inputs

Display KeyExample InputDescriptionRestrictions
User ID
Optional
"user_123"Stable user identifierRequired if no Anonymous ID
Anonymous ID
Optional
"anon_abc"Device/session identifierRequired if no User ID
Traits
Optional
{"plan":"pro","email":"a@b.com"}User traitsJSON object
Timestamp
Optional
"2025-11-15T10:23:00Z"Event timestampISO 8601
Context
Optional
{"ip":"1.2.3.4"}Context info (ip, userAgent, …)JSON object
Integrations
Optional
{"All":true}Destination togglesJSON object
Message ID
Optional
"m-123"Idempotency keyString

Example output

json
{ "success": true }

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

Track Event ​

Record a user action.

Inputs

Display KeyExample InputDescriptionRestrictions
User ID
Optional
"user_123"Stable user identifierRequired if no Anonymous ID
Anonymous ID
Optional
"anon_abc"Device/session identifierRequired if no User ID
Event"Item Purchased"Event nameRequired
Properties
Optional
{"sku":"123","price":10}Event propertiesJSON object
Timestamp
Optional
"2025-11-15T10:23:00Z"Event timestampISO 8601
Context
Optional
{"ip":"1.2.3.4"}Context infoJSON object
Integrations
Optional
{"All":true}Destination togglesJSON object
Message ID
Optional
"m-456"Idempotency keyString

Example output

json
{ "success": true }

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

Track Page View ​

Record a page call for server-side parity.

Inputs

Display KeyExample InputDescriptionRestrictions
User ID
Optional
"user_123"Stable user identifierRequired if no Anonymous ID
Anonymous ID
Optional
"anon_abc"Device/session identifierRequired if no User ID
Page Name
Optional
"Pricing"Page nameString
Category
Optional
"Marketing"Page categoryString
Properties
Optional
{"path":"/pricing"}Page propertiesJSON object
Timestamp
Optional
"2025-11-15T10:23:00Z"Event timestampISO 8601
Context
Optional
{"ip":"1.2.3.4"}Context infoJSON object
Integrations
Optional
{"All":true}Destination togglesJSON object
Message ID
Optional
"m-789"Idempotency keyString

Example output

json
{ "success": true }

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

Group User ​

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

Inputs

Display KeyExample InputDescriptionRestrictions
User ID
Optional
"user_123"Stable user identifierRequired if no Anonymous ID
Anonymous ID
Optional
"anon_abc"Device/session identifierRequired if no User ID
Group ID"org_456"Organization/account identifierRequired
Traits
Optional
{"plan":"enterprise"}Group traitsJSON object
Timestamp
Optional
"2025-11-15T10:23:00Z"Event timestampISO 8601
Context
Optional
{"ip":"1.2.3.4"}Context infoJSON object
Integrations
Optional
{"All":true}Destination togglesJSON object
Message ID
Optional
"m-101"Idempotency keyString

Example output

json
{ "success": true }

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

Alias User ​

Merge a previous identity into a new one, for example the anonymous ID of a visitor into their user ID after sign-up.

Inputs

Display KeyExample InputDescriptionRestrictions
Previous ID"anon_abc"Identity to merge, typically the anonymous IDRequired. Backend workflows only: in interface workflows, Segment uses the current browser identity
User ID"user_123"New identity, typically the user ID after sign-up or loginRequired in backend workflows
Timestamp
Optional
"2025-11-15T10:23:00Z"Event timestampISO 8601
Context
Optional
{"ip":"1.2.3.4"}Context infoJSON object
Integrations
Optional
{"All":true}Destination togglesJSON object
Message ID
Optional
"m-202"Idempotency keyString

Example output

json
{ "success": true }

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

Track Screen View ​

Record a screen view, common in mobile or app-like flows.

Inputs

Display KeyExample InputDescriptionRestrictions
User ID
Optional
"user_123"Stable user identifierRequired if no Anonymous ID
Anonymous ID
Optional
"anon_abc"Device/session identifierRequired if no User ID
Screen Name"Settings"Screen nameRequired
Category
Optional
"Account"Screen categoryString
Properties
Optional
{"tab":"billing"}Screen propertiesJSON object
Timestamp
Optional
"2025-11-15T10:23:00Z"Event timestampISO 8601
Context
Optional
{"ip":"1.2.3.4"}Context infoJSON object
Integrations
Optional
{"All":true}Destination togglesJSON object
Message ID
Optional
"m-303"Idempotency keyString

Example output

json
{ "success": true }

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

Error handling ​

Error code and typeReason
401 UnauthorizedInvalid or missing Write Key.
400 Bad RequestInvalid payload shape or required fields missing.
403 ForbiddenWrite Key lacks access or workspace restrictions.
429 Too Many RequestsRate limited; backoff and retry.
500 Internal Server ErrorProvider-side error; retry with backoff.

FAQs ​

What source type should I select in Segment?

It depends on where your actions run. Backend actions use Segment's HTTP API and need the Write Key of a Node.js source (Backend Write Key). Interface actions run in the browser and need the Write Key of a JavaScript source (Frontend Write Key). If you use both, create both sources.

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.