Skip to main content

​
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

1

Create an account

Sign up at struct.to/dashboard and create an organisation.
2

Generate an API key

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

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.
4

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 }
  }'
5

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

EventDescription
trader_first_tradeTracked trader executes their first-ever trade on Polymarket
trader_new_marketTrader places their first trade in a specific market (fires once per trader+market pair)
trader_new_tradeEvery order-filled trade by a tracked trader
trader_trade_eventTyped prediction-trade stream events for a tracked trader
trader_whale_tradeTrade exceeds the configured size and probability thresholds
trader_global_pnlTrader’s global PnL (across all markets) crosses a configured threshold
trader_market_pnlTrader’s per-market PnL crosses a configured threshold
trader_event_pnlTrader’s per-event PnL crosses a configured threshold

​
Market & Event Metrics

EventDescription
condition_metricsMarket’s volume or transaction metrics cross a configured threshold
event_metricsEvent’s aggregated volume or transaction metrics cross a configured threshold
position_metricsPosition’s volume or transaction metrics cross a configured threshold
tag_metricsTag’s aggregated volume or transaction metrics cross a configured threshold

​
Volume Milestones

EventDescription
market_volume_milestoneMarket’s trading volume crosses a USD milestone
event_volume_milestoneEvent’s aggregated trading volume crosses a USD milestone
position_volume_milestonePosition’s trading volume crosses a USD milestone

​
Spikes

EventDescription
price_spikePosition’s raw trade price (not enriched probability) spikes within a window
price_thresholdOutcome’s price crosses a target level you set (edge-triggered, fires once per crossing)
market_volume_spikeMarket’s volume in a timeframe exceeds the configured baseline by the spike ratio
event_volume_spikeEvent’s aggregated volume in a timeframe exceeds the configured baseline by the spike ratio
position_volume_spikePosition’s volume in a timeframe exceeds the configured baseline by the spike ratio

​
Market Lifecycle

EventDescription
close_to_bondTrade occurs at a near-certain-outcome price
market_createdNew prediction market is detected on-chain and enriched with metadata
oracle_eventsOn-chain oracle activity: resolution, dispute, assertion, emergency, and related events
market_resolvedMarket reaches a terminal resolution, deduplicated to one delivery with the winning outcome
market_disputedProposed market resolution is challenged on-chain

​
Asset Prices

EventDescription
asset_price_tickEvery raw Chainlink price tick for a tracked crypto asset
asset_price_window_updateDelivered 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:
MethodEndpointDescription
GET/v1/webhooksList all your webhook subscriptions
GET/v1/webhooks/eventsList 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-secretRotate the signing secret
POST/v1/webhooks/{id}/testSend a test payload
GET/v1/webhooks/{id}/logsInspect 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.
Last modified on June 16, 2026