Why add TrackLayer alongside Segment
Segment is often the first place teams centralize customer event collection. It gives product, data, and engineering teams a common vocabulary for sources, destinations, traits, and event names. But many downstream platforms need more than broad routing. Paid media APIs need hashed identifiers and dedup keys, email tools need profile-ready lifecycle events, ecommerce reporting needs stable order fields, and warehouses need payloads that do not change every time a frontend implementation changes.
TrackLayer works well as a Segment destination because it gives those high-value events a second processing stage. Segment can keep collecting and dispatching, while TrackLayer turns selected calls into canonical server-side events with consent checks, normalized properties, destination-specific naming, retries, and observability. The result is less pressure on the browser and less custom glue code in each downstream integration.
Prerequisites
A Segment workspace with admin access to add destinations, configure source filters, inspect delivery attempts, and send test events.
A TrackLayer workspace with an inbound webhook endpoint, destination secret, environment name, and permission to connect downstream platforms.
A shared event dictionary that lists Segment event names, required properties, canonical TrackLayer names, consent rules, and deduplication keys.
A test user and test order path that can produce identify, add to cart, checkout, purchase, and lead events without touching real customers.
Step-by-step setup
Add a custom webhook destination
In Segment, open the source that already receives your ecommerce or application events, then add a webhook destination for TrackLayer. Use the TrackLayer inbound URL for the current environment and start with only a small event allowlist. A narrow first pass keeps delivery logs readable while you validate payload shape, identity fields, timestamps, and consent properties.
Destination URL
https://inbound.tracklayer.io/segment/events
Allowed events
Product Viewed
Product Added
Checkout Started
Order Completed
Lead SubmittedConfigure headers and signing
Send a static destination key and a signature header from Segment to TrackLayer. TrackLayer should reject requests that do not include the expected account, environment, content type, timestamp, and signature. Keep the secret server-side, rotate it on a schedule, and create separate credentials for staging and production so test traffic cannot leak into live destinations.
Content-Type: application/json
X-TrackLayer-Account: acct_live_123
X-TrackLayer-Environment: production
X-TrackLayer-Timestamp: 2026-04-23T10:15:30Z
X-TrackLayer-Signature: sha256=example_signatureMap Segment events into canonical events
Segment event names usually describe product analytics language, while TrackLayer canonical names describe downstream business actions. Create a mapping table before activation. Keep property transforms explicit: revenue becomes value, currency stays currency, products become items, and orderId becomes order_id. This gives ads, email, analytics, and warehouse destinations the same contract.
{
"segment_event": "Order Completed",
"tracklayer_event": "purchase",
"properties": {
"event_id": "seg_msg_01HX9",
"order_id": "ORD-10492",
"value": 129.95,
"currency": "EUR",
"items": ["SKU-481", "SKU-812"]
}
}Send a controlled test
Use Segment's destination tester or a staging source to send one identify call and one track call for the same test user. Confirm TrackLayer accepts the request, resolves the profile, stores the original Segment message ID, and shows the transformed canonical event. Do not enable broad source filters until the first event can be traced end to end.
{
"type": "track",
"event": "Product Added",
"messageId": "seg_test_481",
"userId": "cust_34982",
"anonymousId": "anon_8dca",
"properties": {
"product_id": "SKU-481",
"price": 89.95,
"currency": "EUR"
}
}Connect downstream platforms
After Segment delivery and TrackLayer normalization are stable, connect the platforms that should receive canonical events. Meta CAPI, Google Ads, Klaviyo, TikTok, analytics warehouses, and internal webhooks can each use the same TrackLayer event while receiving destination-specific names, identity fields, consent flags, and retry behavior.
Segment → TrackLayer canonical events → Meta CAPI
Segment → TrackLayer canonical events → Google Ads
Segment → TrackLayer canonical events → Klaviyo
Segment → TrackLayer canonical events → WarehouseEvent mapping
Keep Segment names readable for product teams and TrackLayer names stable for downstream systems. A mapping table prevents ad platforms, email tools, and warehouse models from depending on frontend naming decisions. Version this table whenever a new source starts sending events or marketers add a new activation path.
| Segment event | TrackLayer canonical | Downstream name |
|---|---|---|
| Product Viewed | view_content | ViewContent |
| Product Added | add_to_cart | AddToCart |
| Checkout Started | begin_checkout | InitiateCheckout |
| Order Completed | purchase | Purchase |
| Lead Submitted | lead | Lead |
| Signed Up | sign_up | CompleteRegistration |
| Products Searched | search | Search |
Identify vs track
Segment identify calls describe the person. They should update TrackLayer profile state with userId, anonymousId, email, phone, locale, country, consent flags, acquisition source, and other traits that improve matching or segmentation. Identify calls should not become conversion events by themselves. Their job is to prepare identity so later track calls can be matched and routed with confidence.
Segment track calls describe something the person did. Those calls become TrackLayer canonical events when they represent a business action: product viewed, product added, checkout started, order completed, lead submitted, signup, search, refund, or a similar lifecycle moment. TrackLayer should link track calls to the latest known identity, preserve the Segment messageId, and generate a stable event_id that downstream destinations can reuse.
identify → update profile and identity graph
track → create canonical event and route downstreamTesting
Check Segment delivery attempts
Open the destination debugger and confirm TrackLayer receives a 2xx response for the test identify and track calls. Inspect the request body and headers before widening the event allowlist.
Compare raw and canonical events
In TrackLayer, confirm the raw Segment message ID is stored, the canonical name is correct, event time is preserved, and transformed properties match the mapping table.
Verify one downstream platform
Send the canonical event to one connected destination first, then confirm diagnostics show the expected event name, user identifiers, consent state, currency, value, and dedup key.
Troubleshooting
401 unauthorized
Confirm the account header, environment header, timestamp, and signature secret match the TrackLayer endpoint. Rotate the secret if it was copied into a client-visible setting.
events accepted but unmapped
Add the Segment event name to the mapping table exactly as delivered. Segment event names are case-sensitive, and small naming drift can bypass canonical routing.
missing user identity
Forward userId, anonymousId, email, phone, and traits when available. TrackLayer can merge identity over time, but downstream platforms need enough fields for matching.
duplicate purchases
Use Segment messageId plus order_id as the dedup foundation. TrackLayer retries and downstream sends should reuse the same event_id for the same completed order.
Common questions
Does TrackLayer replace Segment?
No. Segment remains useful for collection, product analytics, and routing. TrackLayer sits beside it as a destination that normalizes selected events for server-side marketing, ads, ecommerce, and warehouse activation.
Should every Segment event go to TrackLayer?
Usually no. Send the events that need destination-grade identity, consent, deduplication, and downstream transformation. Page noise, UI clicks, and internal analytics events should stay out unless they power a specific use case.
Can identify calls create TrackLayer profiles?
Yes. Segment identify calls are useful for updating customer traits, joining anonymous and known activity, and preparing profile fields before later track calls trigger downstream destinations.
Where should consent rules live?
Keep the source consent state in Segment traits or event context, then enforce destination-specific rules inside TrackLayer. That keeps one collection event usable across platforms with different consent requirements.
Related implementation guides
Identity resolution guide
Design stable customer identifiers before routing events across Segment, TrackLayer, ad platforms, email tools, and warehouses.
Read guide →Deduplication explained
Keep one customer action as one event across Segment retries, TrackLayer normalization, browser tracking, and destination APIs.
Read guide →Klaviyo sync guide
Use TrackLayer canonical events to trigger Klaviyo flows with profile identity, clean metric names, and reliable ecommerce properties.
Read guide →