# Understanding Signals

> Source: https://docs.trailspark.ai/docs/signals-overview

## Signal Pipeline

Signals flow through TrailSpark in a defined pipeline:

```
Source → Staging → Mapping Rules → Processing → Lead Profile → Evaluation
```

1. **Staging**: Raw signals arrive via webhooks and are stored in the `signal_staging` table
2. **Mapping**: Signals are matched against your configured mapping rules
3. **Processing**: Matched signals create or update leads and accounts
4. **Evaluation**: Processed signals contribute to lead and account scores

## Signal Sources

TrailSpark auto-detects the source from payload structure. Recognized sources:

| Source | How signals arrive |
|--------|-------------------|
| **Segment** | Identify, track, and page events via webhook destination |
| **Marketo** | Marketing automation events (detected by `mktLeadId` in payload) |
| **HubSpot** | CRM events (detected by `portalId` or `hs_object_id`) |
| **Salesforce** | CRM events (detected by `sObject` in payload) |
| **Custom / Generic** | Any system sending HTTP POST to your webhook endpoint. Falls back to `generic` if no source is detected |

You can also explicitly set the source via the source-specific webhook URL (`/api/signal-staging/webhook/{source}/{apiKey}`) or by including an `X-Source` header or `source` field in the payload.

## Signal Types

When creating mapping rules, you assign a signal type to categorize the signal:

| Type | Use for |
|------|---------|
| Page View | Website page visits |
| Form Fill | Form submissions |
| Product Activity | In-product actions |
| Sales Event | Sales interactions |
| Email Open | Email opens |
| Email Click | Email link clicks |

## Signal Components

Each staged signal contains:

| Field | Description |
|-------|-------------|
| **Signal Source** | Origin system (segment, marketo, hubspot, custom) |
| **Event Type** | Technical event identifier (track, page, identify) |
| **Payload** | Full JSON event data |
| **Processing Status** | `pending`, `processing`, `completed`, `failed`, `skipped`, `permanently_failed` |
| **Mapped Rule** | ID of the mapping rule that matched (after processing) |

## Signal Mapping Page

Navigate to **Signal Mapping** from the main navigation. The page has two tabs:

- **Signal Rules** -- View, create, edit, and delete mapping rules
- **Signal Queue** -- View staged signals grouped by pattern, and create rules from them

<img src="/api/images/939fc405-2f36-44ce-a52d-226812074ab4/file" alt="Trailspark Signal Mapping Page" width="600" />

## Signal Processing States

These are the `processingStatus` values on staged signals:

| Status | Meaning |
|--------|---------|
| `pending` | Awaiting processing |
| `processing` | Currently being processed |
| `completed` | Successfully matched and stored |
| `failed` | Processing encountered an error (retried up to 3 times) |
| `skipped` | No matching rule found or limit reached |
| `permanently_failed` | Failed after max retries, will not be retried |

## Plan Limits

Each plan defines a `maxRawSignals` limit (monthly) and a `signalRetentionPeriod` (in days). When you approach or reach your raw signal limit, usage warnings display in the Signal Explorer and webhook responses return `429` status codes. Paid plans can enable usage overages in **Settings** > **Billing**.

## Next Steps

- [Creating Signal Mapping Rules](/docs/creating-signal-mapping)
- [Signal Explorer](/docs/signal-explorer)
- [Webhook Configuration](/docs/webhook-configuration)