Overview
Webhooks let you subscribe to real-time events from Polymarket — like trades, PnL changes, volume milestones, and probability spikes — delivered directly to your server as HTTP POST requests.
Instead of polling the API, webhooks push data to you the moment something happens.
Base URL
All webhook management requests use the same base URL as the REST API:
Setting Up Your First Webhook
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 events you want to listen to: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",
"events": ["first_trade", "probability_spike"],
"secret": "your_signing_secret"
}'
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_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 |
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 |
|---|
probability_spike | Position’s probability changes by at least the configured percentage within a timeframe |
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 |
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
Verifying Payloads
If you provide a secret when creating your webhook, each delivery will include an HMAC signature you can use to verify the payload originated from Struct.
Always verify webhook signatures in production to prevent spoofed requests.
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/{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}/test | Send a test payload |
Limits
You can create up to 100 webhooks per account. Rate limits on the management API depend on your plan — see Pricing & Ratelimits for details.
If you need higher limits, reach out to us at support@struct.to.
