Getting Started - Struct Docs

Overview

Webhooks let you subscribe to real-time events from Polymarket (like trades, PnL changes, volume milestones, and price spikes) delivered directly to your server as HTTP POST requests. Instead of polling the API, webhooks push data to you the moment something happens. Deliveries are event-driven, evaluated inline as on-chain activity is ingested rather than on a polling cycle.

Base URL

All webhook management requests use the same base URL as the REST API:

https://api.struct.to

Setting Up Your First Webhook

Create an account

Generate an API key

Navigate to the API Keys section in your dashboard and create a new key.

Prepare your endpoint

Set up an HTTP endpoint on your server that accepts POST requests and returns a 200 status code. Your endpoint must be publicly accessible.

Create a webhook subscription

Register your endpoint with the event you want to listen to. Each subscription targets a single event with its own filters — create one subscription per event:

curl -X POST https://api.struct.to/v1/webhooks \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks",
    "event": "trader_whale_trade",
    "secret": "your_signing_secret",
    "filters": { "min_usd_value": 10000 }
  }'

const response = await fetch("https://api.struct.to/v1/webhooks", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://your-server.com/webhooks",
    event: "trader_whale_trade",
    secret: "your_signing_secret",
    filters: { min_usd_value: 10000 },
  }),
});

const data = await response.json();

import requests

response = requests.post(
    "https://api.struct.to/v1/webhooks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://your-server.com/webhooks",
        "event": "trader_whale_trade",
        "secret": "your_signing_secret",
        "filters": {"min_usd_value": 10000},
    },
)

data = response.json()

Test your webhook

Send a test payload to verify connectivity:

curl -X POST https://api.struct.to/v1/webhooks/{webhook_id}/test \
  -H "X-API-Key: YOUR_API_KEY"

Available Events

Trader Events

Event	Description
`trader_first_trade`	Tracked trader executes their first-ever trade on Polymarket
`trader_new_market`	Trader places their first trade in a specific market (fires once per trader+market pair)
`trader_new_trade`	Every order-filled trade by a tracked trader
`trader_trade_event`	Typed prediction-trade stream events for a tracked trader
`trader_whale_trade`	Trade exceeds the configured size and probability thresholds
`trader_global_pnl`	Trader’s global PnL (across all markets) crosses a configured threshold
`trader_market_pnl`	Trader’s per-market PnL crosses a configured threshold
`trader_event_pnl`	Trader’s per-event PnL crosses a configured threshold

Market & Event Metrics

Event	Description
`condition_metrics`	Market’s volume or transaction metrics cross a configured threshold
`event_metrics`	Event’s aggregated volume or transaction metrics cross a configured threshold
`position_metrics`	Position’s volume or transaction metrics cross a configured threshold
`tag_metrics`	Tag’s aggregated volume or transaction metrics cross a configured threshold

Volume Milestones

Event	Description
`market_volume_milestone`	Market’s trading volume crosses a USD milestone
`event_volume_milestone`	Event’s aggregated trading volume crosses a USD milestone
`position_volume_milestone`	Position’s trading volume crosses a USD milestone

Spikes

Event	Description
`price_spike`	Position’s raw trade price (not enriched probability) spikes within a window
`price_threshold`	Outcome’s price crosses a target level you set (edge-triggered, fires once per crossing)
`market_volume_spike`	Market’s volume in a timeframe exceeds the configured baseline by the spike ratio
`event_volume_spike`	Event’s aggregated volume in a timeframe exceeds the configured baseline by the spike ratio
`position_volume_spike`	Position’s volume in a timeframe exceeds the configured baseline by the spike ratio

Market Lifecycle

Event	Description
`close_to_bond`	Trade occurs at a near-certain-outcome price
`market_created`	New prediction market is detected on-chain and enriched with metadata
`oracle_events`	On-chain oracle activity: resolution, dispute, assertion, emergency, and related events
`market_resolved`	Market reaches a terminal resolution, deduplicated to one delivery with the winning outcome
`market_disputed`	Proposed market resolution is challenged on-chain

Asset Prices

Event	Description
`asset_price_tick`	Every raw Chainlink price tick for a tracked crypto asset
`asset_price_window_update`	Delivered twice per candle: once on open and once on close

Filtering

Webhooks support granular filters so you only receive the events you care about. Filters can be passed when creating or updating a webhook:

Wallet address: track specific traders
Market / condition ID: target specific markets
Event slug: filter by event
USD thresholds: minimum/maximum value bounds
Probability range: 0.0 to 1.0
PnL bounds and volume minimums

Every event also accepts one_shot to fire once and then delete the subscription automatically. See Fire-and-Delete.

Verifying Payloads

If you provide a secret when creating your webhook, each delivery includes an X-Webhook-Signature header (HMAC-SHA256 of the raw body) you can use to verify the payload originated from Struct.

Always verify webhook signatures in production to prevent spoofed requests. See Signature Verification for the scheme and copy-paste verification code.

Managing Webhooks

You can list, update, pause, and delete your webhooks via the API:

Method	Endpoint	Description
`GET`	`/v1/webhooks`	List all your webhook subscriptions
`GET`	`/v1/webhooks/events`	List available event types
`GET`	`/v1/webhooks/{id}`	Get a specific webhook
`PUT`	`/v1/webhooks/{id}`	Update a webhook’s URL, events, filters, or status
`DELETE`	`/v1/webhooks/{id}`	Delete a webhook
`POST`	`/v1/webhooks/{id}/rotate-secret`	Rotate the signing secret
`POST`	`/v1/webhooks/{id}/test`	Send a test payload
`GET`	`/v1/webhooks/{id}/logs`	Inspect recent delivery logs (7-day retention)

Limits

How many webhook subscriptions you can create depends on your plan: 10 on Free, 5,000 on Hobby, 25,000 on Startup, and 100,000 on Scale (Enterprise is unlimited). Rate limits on the management API also depend on your plan; see Pricing & Ratelimits for details. If you need higher limits, reach out to us at support@struct.to.

​Overview

​Base URL

​Setting Up Your First Webhook

​Available Events

​Trader Events

​Market & Event Metrics

​Volume Milestones

​Spikes

​Market Lifecycle

​Asset Prices

​Filtering

​Verifying Payloads

​Managing Webhooks

​Limits

Overview

Base URL

Setting Up Your First Webhook

Available Events

Trader Events

Market & Event Metrics

Volume Milestones

Spikes

Market Lifecycle

Asset Prices

Filtering

Verifying Payloads

Managing Webhooks

Limits