Custom Integrations: Outgoing Webhooks and the Read API

Not every tool in your stack has a native Stairoids integration — and that’s fine. For anything else, Stairoids can send action triggers out to your own endpoint via outgoing webhooks, and you can pull your scored data with the read-only API. Wire these up directly, or through a no-code platform like n8n, Make, or Zapier.

There is currently no public endpoint for pushing signals into Stairoids over the API. Signals arrive through native integrations and incoming automations. This page covers receiving action triggers out of Stairoids and reading your data.

Receive an action trigger via webhook

Configure an outgoing automation in Stairoids with the action type Webhook. When the automation fires, Stairoids sends a POST request to the URL you configure with the full signal and contact context. Use this when you want a non-native tool to respond to something that happened inside Stairoids. When to use this pattern:

You want to trigger an action in a tool Stairoids doesn’t natively support
You’re building a custom integration that needs to receive structured event data
You want to log Stairoids automation events into your own data store

Payload

{
  "event": "automation.action_triggered",
  "automation_id": "auto_01j4k8m2n3p5q6r7s8",
  "automation_name": "High-intent trial → notify sales",
  "triggered_at": "2024-09-01T14:32:05Z",
  "account": {
    "id": "acc_01j4k8m2n3p5q6r7",
    "name": "Acme Corp",
    "domain": "acmecorp.com"
  },
  "contact": {
    "id": "con_01j4k8m2n3p5q6r8",
    "email": "jane.doe@acmecorp.com",
    "first_name": "Jane",
    "last_name": "Doe"
  },
  "signal": {
    "id": "sig_01j4k8m2n3p5q6r7s8t9u0v1",
    "type": "product_trial_started",
    "source": "internal_app",
    "properties": {
      "plan": "pro_trial",
      "trial_ends_at": "2024-09-15T00:00:00Z"
    },
    "created_at": "2024-09-01T14:32:00Z"
  }
}

Verifying the HMAC-SHA256 signature

Every outgoing webhook includes an X-Stairoids-Signature header. Verify it to confirm the request genuinely came from Stairoids and hasn’t been tampered with. The signature is computed as:

HMAC-SHA256(webhook_secret, raw_request_body)

Your webhook secret is shown once when you configure the Webhook action in Stairoids. Store it securely. Here’s how to verify it:

Node.js
Python

const crypto = require('crypto');

function verifyStairoidsSignature(rawBody, receivedSignature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');

  const trusted = Buffer.from(`sha256=${expectedSignature}`, 'ascii');
  const received = Buffer.from(receivedSignature, 'ascii');

  // Use timingSafeEqual to prevent timing attacks
  return crypto.timingSafeEqual(trusted, received);
}

// In your Express route handler:
app.post('/webhook/stairoids', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-stairoids-signature'];
  const isValid = verifyStairoidsSignature(req.body, signature, process.env.STAIROIDS_WEBHOOK_SECRET);

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  const payload = JSON.parse(req.body);
  // Handle payload...
  res.status(200).send('OK');
});

import hmac
import hashlib
import os
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = os.environ.get("STAIROIDS_WEBHOOK_SECRET")

def verify_signature(raw_body: bytes, received_signature: str) -> bool:
    expected = hmac.new(
        WEBHOOK_SECRET.encode("utf-8"),
        raw_body,
        hashlib.sha256
    ).hexdigest()
    expected_header = f"sha256={expected}"
    return hmac.compare_digest(expected_header, received_signature)

@app.route("/webhook/stairoids", methods=["POST"])
def stairoids_webhook():
    signature = request.headers.get("X-Stairoids-Signature", "")
    raw_body = request.get_data()

    if not verify_signature(raw_body, signature):
        abort(401)

    payload = request.get_json(force=True)
    # Handle payload...
    return "OK", 200

Pull your data with the read-only API

To read your scored companies, buying-signal activity, funnel, attribution, and LinkedIn ad engagement from your own systems, use the read-only public API. It authenticates with an X-Api-Key header. See the API Reference and Authentication.

Prefer no code? Use n8n, Make, or Zapier to receive Stairoids outgoing webhooks with their built-in Webhook nodes, then fan out to tools like Slack, Notion, or Google Sheets.

Get Started

Signals

Integrations

Configuration

Resources

Custom Integrations: Outgoing Webhooks and the Read API

Receive an action trigger via webhook

Payload

Verifying the HMAC-SHA256 signature

Pull your data with the read-only API

​Receive an action trigger via webhook

​Payload

​Verifying the HMAC-SHA256 signature

​Pull your data with the read-only API

Receive an action trigger via webhook

Payload

Verifying the HMAC-SHA256 signature

Pull your data with the read-only API