# Sending Signals from Segment

> Source: https://docs.trailspark.ai/webhooks-api/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](https://docs.trailspark.ai/webhooks-api/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** -- You've either exceeded the request rate limit, or gone past **twice** your Trailspark plan's ingested-signal limit. Between the limit and twice the limit, signals are still collected at no extra charge but held (paused signals don't update your scores, and they're deleted at the end of the billing period); only beyond that are they rejected. Tighten destination filters to reduce volume, enable usage overages, or upgrade your plan. That free extra room isn't permanent: on a paid plan, ending **three billing periods in a row** over the allowance without pay-as-you-go turned on removes it for good, after which signals past the allowance are rejected immediately. A period back inside the allowance resets the count.

**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](https://docs.trailspark.ai/webhooks-api/webhook-configuration)
- [Webhook Payload Format](https://docs.trailspark.ai/webhooks-api/webhook-payload-format)
- [Creating Signal Mapping](https://docs.trailspark.ai/signal-management/creating-signal-mapping)
- [Segment integration overview](https://www.trailspark.ai/integrations/segment) — what the Segment integration does, which events Trailspark uses, and what it sends back