# Sending Signals from Segment

> Source: https://docs.trailspark.ai/docs/segment-webhook-setup

## Overview

Send Segment events to TrailSpark using a Webhook destination. TrailSpark auto-detects Segment payloads and handles identity resolution via `anonymousId`.

> [!NOTE]
> The native Segment integration has been deprecated. Use the generic Webhooks destination described below.

## Webhook Endpoint

```
POST https://app.trailspark.ai/api/signal-staging/webhook/{apiKey}
```

Create an API key at **Settings** > **API Keys** with endpoint type **Signal Staging**. See [Managing API Keys](/docs/api-keys).

## Adding the Webhook Destination

1. In Segment, go to **Connections** > **Destinations** > **Add Destination**
2. Search for **Webhooks (Actions)** and select it
3. Choose the source to connect
4. Configure the destination:

| Setting | Value |
|---------|-------|
| **URL** | `https://app.trailspark.ai/api/signal-staging/webhook/{apiKey}` |
| **Method** | `POST` |
| **Content-Type** | `application/json` |
| **Headers** | Add `X-Api-Secret: {secret}` if your API key has a secret configured |

5. Enable the destination

## Event Filtering

Each signal counts against your plan limits. Use Segment's **Destination Filters** to send only events that matter for lead scoring.

### Recommended: Allow List

Create a destination filter that only allows specific event types and names through.

**Always send:**

- `identify` -- required for identity resolution (links `anonymousId` to email and traits)

**High-value track events to send:**

- Form submissions (demo requests, contact sales, content downloads)
- Pricing page views
- Product signups and trial starts
- Feature activation events
- Key product milestones (first project created, invited team member)

**Example allow list:**

```
identify
Form Submitted
Demo Requested
Trial Started
Pricing Page Viewed
Feature Activated
Signed Up
Invite Sent
```

### Events to Filter Out

- Generic page views across every page (high volume, low signal value)
- UI interaction events (button clicks, tab switches, dropdown opens)
- Internal/admin user activity
- Health checks, error tracking, performance monitoring
- Analytics-only events not related to buying intent

> [!TIP]
> Start with `identify` plus 5-10 high-intent track events. You can always add more later from the Signal Queue.

### Page Calls

Page calls can generate significant volume. If you want page-level scoring, filter to high-value URL patterns only (e.g., `/pricing`, `/case-studies`, `/docs`). Do not send all page views unfiltered.

## How TrailSpark Processes Segment Events

TrailSpark auto-detects Segment payloads by recognizing the `type`, `anonymousId`, and `messageId` fields. No additional configuration is needed.

| Segment Call Type | How TrailSpark Handles It |
|-------------------|---------------------------|
| **identify** | Creates an identity resolution record linking `anonymousId` to email. Captures traits (name, company, title) for lead enrichment |
| **track** | Stored as a signal. The `event` field becomes the signal event name. `properties` are available for signal mapping rules |
| **page** | Stored as a page view signal. `properties.url` and `properties.name` are available for mapping |

### Anonymous Identity Resolution

Segment's `anonymousId` enables cold storage rehydration. When a visitor browses anonymously, signals are stored in cold storage. Once that visitor is identified via an `identify` call (with email in traits), TrailSpark links all prior anonymous signals to the newly created lead.

## Signal Mapping

Segment events appear in **Signal Mapping** > **Signal Queue** with source auto-detected as `segment`, grouped by event name.

When creating mapping rules from the queue:

- TrailSpark pre-fills conditions from the Segment payload structure
- Map `traits.email` or `properties.email` to the email field for lead identification
- Map `traits.company`, `traits.title`, `traits.name` for lead enrichment
- Use dot notation to access nested fields (e.g., `properties.form_name`, `context.page.url`)

## Best Practices

- Use Segment's **Event Tester** to verify events reach TrailSpark before fully enabling the destination
- Monitor the **Signal Queue** in TrailSpark after enabling to check for unexpected event volume
- If sending page calls, filter to specific URL patterns rather than all pages
- Use Segment Protocols or a tracking plan to keep event names consistent across sources
- Review your destination filter quarterly as your tracking plan evolves

## Troubleshooting

**Events not arriving** -- Verify the destination is enabled and the webhook URL includes your API key. Check Segment's **Event Delivery** tab for error responses. Confirm destination filters are not blocking all events.

**429 responses in Segment** -- Your TrailSpark plan's raw signal limit has been reached. Tighten destination filters to reduce volume, or upgrade your plan.

**Duplicate signals** -- Segment guarantees at-least-once delivery. TrailSpark deduplicates by content hash during signal processing. No action needed.

**Identity not resolving** -- Ensure `identify` calls include the `email` trait. Without email, TrailSpark cannot create a lead record. Check that `identify` is included in your destination filter allow list.

## Next Steps

- [Webhook Configuration](/docs/webhook-configuration)
- [Webhook Payload Format](/docs/webhook-payload-format)
- [Creating Signal Mapping](/docs/creating-signal-mapping)