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 — a signal with no matching rule yet stays here, in case you add one later |
processing | Currently being processed |
completed | Successfully matched and stored |
failed | Processing encountered an error (retried up to 3 times) |
skipped | A plan limit was reached, so the signal is paused; it's picked up again once capacity frees up |
permanently_failed | Failed after max retries, will not be retried |
Plan Limits
Each plan includes a monthly ingested-signal allowance and a signal retention window (in days). As you approach the allowance, usage warnings display in the Signal Explorer.
Past the allowance, TrailSpark keeps collecting your signals at no extra charge up to twice the allowance and holds them — the Usage page marks them Paused. Paused signals don't update your scores, and they're deleted when the billing period ends. Enabling usage overages in Settings > Billing on a paid plan, or upgrading, resumes them immediately. Beyond twice the allowance, webhook responses return 429 status codes and new signals are rejected until the next billing period.