Understanding Signals
Signal Pipeline
Signals flow through TrailSpark in a defined pipeline:
Source → Staging → Mapping Rules → Processing → Lead Profile → Evaluation
- Staging: Raw signals arrive via webhooks and are stored in the
signal_stagingtable - Mapping: Signals are matched against your configured mapping rules
- Processing: Matched signals create or update leads and accounts
- 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
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.