> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stairoids.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Incoming Automations: Route Signals Into Stairoids
> Incoming automations define how engagement signals flow into Stairoids from native integrations, webhook listeners, and the direct REST API.
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](/signals/overview#signal-anatomy). 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 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](/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:**
1. Go to **Settings → Integrations → Incoming**.
2. Click **Add Incoming Automation** and select **Webhook Listener**.
3. Give the automation a name (e.g. `Intercom Conversation Closed`).
4. Stairoids generates a unique URL in the format:
```
https://hooks.stairoids.com/in/wh_01hx7rk2p9tnq4mv
```
5. 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:
```json theme={null}
{
"type": "conversation_closed",
"account": "acme.com",
"contact": "jane@acme.com",
"properties": {
"conversation_id": "12345",
"resolution": "solved",
"channel": "chat"
}
}
```
If your source tool sends a different structure, use [field mapping](#field-mapping) to translate it.
**Securing your webhook:**
Stairoids signs every inbound request with an `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.
```bash theme={null}
# 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
```
**Example — pushing a form submission signal:**
```bash theme={null}
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"
}
}'
```
**Successful response:**
```json theme={null}
{
"id": "sig_01hx4k9mz3fqp7yw",
"status": "ingested",
"score": 18,
"created_at": "2024-06-15T14:32:07Z"
}
```
For the full request and response schema, including all optional fields and error codes, see the [Send Signal API reference](/api-reference/signals/send-signal).
## Creating an Incoming Automation in the UI
Navigate to **Settings → Integrations** in the Stairoids dashboard, then click the **Incoming** tab.
Click **Add Incoming Automation**. A setup panel opens on the right side of the screen.
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.
In the **Field Mapping** section, define how source fields translate to Stairoids signal properties. See [Field Mapping](#field-mapping) below for details.
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` |
**Example mapping for a HubSpot webhook payload:**
```json theme={null}
{
"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` | — |
Any source fields not explicitly mapped can be captured automatically into the `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.