Incoming automations are the entry points for your signal data. Each incoming automation tells Stairoids where to listen for events, how to parse the payload it receives, and how to map source fields onto the canonical signal schema. Once configured, incoming automations run continuously in the background — every qualifying event from your connected tools arrives in Stairoids as a structured, scored signal ready to trigger intelligence and outgoing automations.
Three Ways to Ingest Signals
Native Integration
Webhook Listener
Direct API
Native integrations are the simplest way to get signals into Stairoids. Stairoids maintains first-party connectors for the most common B2B marketing and sales tools. When you connect a supported tool, signals start flowing automatically — no webhook configuration or custom code required.Supported native sources include: HubSpot, Pipedrive, Salesforce, Leadfeeder, HeyReach, Expandi, Lemlist, Mailchimp, Calendly, and Typeform.For each native integration, Stairoids automatically:
- Authenticates using OAuth 2.0 or API key (depending on the tool)
- Subscribes to the relevant event streams
- Maps the tool’s native event fields to Stairoids signal properties
- Begins ingesting historical events from the past 30 days (configurable)
To connect a native integration, navigate to Settings → Integrations and browse the integration catalogue. See the Integrations Overview for a full list of supported tools and setup guides.After connecting a native integration, visit the Signal Timeline on any account record to confirm events are arriving. Native integrations typically deliver the first signals within 60 seconds of connection.
A webhook listener gives you a unique inbound HTTPS endpoint that any tool or service can POST events to. Use this method for tools Stairoids doesn’t natively support, or when you need fine-grained control over which events are forwarded.Finding your webhook URL:
- Go to Settings → Integrations → Incoming.
- Click Add Incoming Automation and select Webhook Listener.
- Give the automation a name (e.g.
Intercom Conversation Closed).
- Stairoids generates a unique URL in the format:
https://hooks.stairoids.com/in/wh_01hx7rk2p9tnq4mv
- Copy this URL and paste it into your source tool’s webhook or HTTP notification settings.
Expected payload format:Stairoids accepts any valid JSON object. You then use the field mapping UI to tell Stairoids which keys in your payload correspond to the type, account, contact, and properties fields. For the best out-of-the-box experience, structure your payload to match the Stairoids signal schema:{
"type": "conversation_closed",
"account": "acme.com",
"contact": "jane@acme.com",
"properties": {
"conversation_id": "12345",
"resolution": "solved",
"channel": "chat"
}
}
X-Stairoids-Signature header using HMAC-SHA256. You can verify this signature in your source tool or middleware if needed. Your signing secret is available in the webhook automation settings.# Example: verifying the signature in a custom proxy
echo -n "$RAW_BODY" | openssl dgst -sha256 -hmac "$SIGNING_SECRET"
Stairoids webhook listeners accept POST requests only. GET and PUT requests return a 405 Method Not Allowed response and are not ingested.
The direct API gives you full programmatic control over signal ingestion. Use POST /v1/signals from your own backend services, data pipelines, or ETL jobs to push any event into Stairoids with complete control over the payload.Authentication: Pass your API key in the Authorization header as a Bearer token. You can generate API keys in Settings → API Keys.Endpoint:POST https://api.stairoids.com/v1/signals
curl -X POST https://api.stairoids.com/v1/signals \
-H "Authorization: Bearer sk_live_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"type": "form_submit",
"account": "acme.com",
"contact": "jane@acme.com",
"source": "custom-backend",
"properties": {
"form_name": "Request a Demo",
"page_url": "https://yoursite.com/demo",
"utm_source": "linkedin"
}
}'
{
"id": "sig_01hx4k9mz3fqp7yw",
"status": "ingested",
"score": 18,
"created_at": "2024-06-15T14:32:07Z"
}
Creating an Incoming Automation in the UI
Open Integration Settings
Navigate to Settings → Integrations in the Stairoids dashboard, then click the Incoming tab.
Add a New Automation
Click Add Incoming Automation. A setup panel opens on the right side of the screen.
Choose Your Ingestion Method
Select one of the three methods: Native Integration, Webhook Listener, or Direct API. For native integrations, choose the specific tool from the catalogue and complete the authentication flow. For webhook listeners, copy the generated URL. For direct API, note your endpoint and authentication details.
Map Your Fields
In the Field Mapping section, define how source fields translate to Stairoids signal properties. See Field Mapping below for details. Name and Save
Give your automation a descriptive name (e.g. HubSpot Form Submissions or Intercom Chat Events), then click Save. The automation becomes active immediately.
Field Mapping
Field mapping tells Stairoids how to translate your source tool’s event structure into the canonical signal schema. You configure mappings in the incoming automation setup panel using a simple key-path syntax.
Each mapping rule has three parts:
| Part | Description | Example |
|---|
| Source path | The dot-notation path to the field in your incoming payload | contact.email |
| Target field | The Stairoids signal property to populate | contact |
| Transform (optional) | A simple transformation to apply: lowercase, extract_domain, to_string | extract_domain |
{
"objectId": 12345,
"subscriptionType": "contact.propertyChange",
"portalId": 98765,
"contact": {
"email": "jane@acme.com",
"company_domain": "acme.com"
}
}
| Source path | Target field | Transform |
|---|
subscriptionType | type | — |
contact.company_domain | account | — |
contact.email | contact | — |
properties object by enabling Auto-capture unmapped fields in the mapping panel.
All incoming automations support custom properties via the properties object. Any field you map to properties.* (e.g. properties.utm_source) is stored alongside the signal and is available as a filter condition in outgoing automations.
Use the Test button in the automation settings panel after setup to send a live test event and verify that your field mapping is working correctly. The test panel shows the raw incoming payload alongside the parsed signal Stairoids would create, so you can spot and fix mapping issues before they affect your data.