Skip to main content
Stairoids can push real-time event notifications to any HTTPS endpoint you register, eliminating the need to poll the API for updates. When a signal is ingested, a score changes, or an automation fires, Stairoids immediately delivers a signed POST request to your registered URL with a structured JSON payload. You can use webhook events to trigger downstream logic in your own systems — logging, alerting, syncing data, or building custom GTM workflows that sit outside the Stairoids automation engine.
You can also register and manage webhooks from the Stairoids dashboard under Settings → Webhooks, without writing any code.

​
Register a Webhook Endpoint

Send a POST request to /v1/webhooks with the URL you want Stairoids to deliver events to, the list of events you want to subscribe to, and an optional secret for signature verification.
cURL
curl -X POST https://api.stairoids.com/v1/webhooks \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/hooks/stairoids",
    "events": ["signal.created", "automation.triggered"],
    "secret": "your-webhook-secret"
  }'

​
Response

{
  "id": "wh_abc123",
  "url": "https://yourapp.com/hooks/stairoids",
  "events": ["signal.created", "automation.triggered"],
  "enabled": true,
  "created_at": "2024-10-15T10:00:00Z"
}
Store the returned id — you will need it to update or delete this endpoint later.

​
List Registered Webhooks

Retrieve all webhook endpoints registered in your workspace.
cURL
curl https://api.stairoids.com/v1/webhooks \
  -H "Authorization: Bearer <api-key>"

{
  "webhooks": [
    {
      "id": "wh_abc123",
      "url": "https://yourapp.com/hooks/stairoids",
      "events": ["signal.created", "automation.triggered"],
      "enabled": true,
      "created_at": "2024-10-15T10:00:00Z"
    }
  ],
  "total": 1
}

​
Delete a Webhook Endpoint

Remove a registered endpoint so Stairoids stops delivering events to it.
cURL
curl -X DELETE https://api.stairoids.com/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer <api-key>"
A successful deletion returns HTTP 204 No Content with an empty body.

​
Delivery Behaviour

When a subscribed event fires, Stairoids sends a POST request to your registered URL with the following headers:
HeaderValue
Content-Typeapplication/json
X-Stairoids-Signaturesha256=<hex-digest> — HMAC-SHA256 of the raw body
X-Stairoids-EventThe event type, e.g. signal.created
X-Stairoids-DeliveryA unique UUID for this delivery attempt
Your endpoint must respond with an HTTP 2xx status code within 10 seconds to acknowledge receipt. Stairoids does not process the response body.

​
Retry Policy

If your endpoint returns a non-2xx response or the connection times out, Stairoids retries delivery with exponential backoff:
1

Attempt 1

Immediate first delivery.
2

Attempt 2

Retry after 1 minute.
3

Attempt 3

Retry after 5 minutes.
4

Attempt 4

Retry after 30 minutes.
5

Attempt 5

Retry after 2 hours.
After five failed attempts the delivery is marked as failed and no further retries are made. You can view delivery logs and replay failed events from Settings → Webhooks → Delivery History in the dashboard.
Return a 200 OK immediately and process the webhook payload asynchronously (e.g. push it to a queue) to avoid timeouts on slow operations. Stairoids only cares that you acknowledged receipt.

​
Explore Further

Event Types & Payloads

Browse every event Stairoids can emit and see full example payloads for each.

Signature Verification

Learn how to validate the X-Stairoids-Signature header to confirm payloads are authentic.