Polymarket Webhooks: Real-Time Notifications for Every Market Event

You need to know the moment it happens

You're building a trading bot on Polymarket. A market you're watching just resolved. A whale dropped $50,000 on a position. The probability on a politics market spiked 15% in two minutes.

By the time you find out, the opportunity is gone.

The obvious approach: poll the API every few seconds. Check for changes. Hope you catch it in time. The better approach: let the data come to you. That's what webhooks do.

What is a webhook?

A webhook is a notification your server receives when something happens. Instead of asking "anything new?" every few seconds, you register a URL and get told automatically.

Technically, it's an HTTP POST request sent to your endpoint when a specific event occurs, with a JSON payload containing the event data. Your server receives it, processes it, and responds with a 200.

Think of it this way: polling is refreshing your email inbox every five seconds. A webhook is push notifications. Same information, completely different efficiency.

You define what you care about, register a URL, and every time that event fires, your endpoint receives the data instantly. No wasted requests, no missed events, no polling intervals.

Why webhooks matter for Polymarket

Prediction markets are time-sensitive by nature. A resolution, a whale trade, a probability spike — seconds matter. The trader who reacts first captures the edge.

Polling introduces latency. If you poll every 10 seconds, you learn about events up to 10 seconds late. That's an eternity when prices move on breaking news. Polling also wastes resources — 99% of your requests return nothing new, but you're still burning API credits and compute on every one of them.

Webhooks flip this model. You receive data the moment it happens. Zero wasted requests. Zero artificial latency. Your system reacts in real time instead of catching up.

One important detail: Polymarket's official API doesn't offer webhooks. Struct does. We're the only service providing developer-grade webhooks for Polymarket data, with 20 event types and 30+ filter fields to target exactly what matters to you.

Webhooks vs WebSockets vs polling

Three ways to get data from an API, each with different tradeoffs:

Polling is the simplest. Send a request, get a response, repeat on a timer. Easy to implement, but wasteful. You're asking "anything new?" hundreds of times for every one time the answer is yes. Latency is bounded by your polling interval — if you poll every 30 seconds, you're always up to 30 seconds behind.

WebSockets give you a persistent, bidirectional connection. Data streams in real time. Great for live price feeds where you need continuous updates. The tradeoff: you need to manage connection state, handle reconnections, deal with backpressure, and maintain heartbeats. More infrastructure to build and maintain.

Webhooks are event-driven. Real time like WebSockets, but stateless like REST. No persistent connection to manage. No reconnection logic. Your server just receives HTTP POST requests when something happens. The tradeoff: you need a publicly accessible endpoint, and you're responsible for handling retries if your server is down.

When to use each: WebSockets for streaming data you consume continuously (live price feeds, order book updates). Webhooks for discrete events you react to (a market resolved, a whale traded, a probability crossed a threshold). Polling when you genuinely only need data periodically and don't care about latency.

What you can listen for

Struct offers 20 webhook event types across four categories.

Market events fire when markets change state:

market_created — a new prediction market goes live
market_volume_milestone — a market crosses a volume threshold ($100K, $1M, etc.)
market_volume_spike — unusual volume surge detected on a market
condition_metrics — updated metrics snapshot for a market (probability, volume, liquidity, traders)
event_metrics — aggregated metrics across all markets in an event group

Trader events fire on individual trader activity:

trader_whale_trade — a large trade above your minimum USD threshold
trader_first_trade — a trader's first-ever trade on a specific market
trader_new_market — a tracked trader enters a market they haven't traded before
trader_global_pnl — portfolio-level P&L update for a tracked trader
trader_market_pnl — per-market P&L update
trader_event_pnl — per-event P&L update

Price events fire on probability and price movements:

probability_spike — sudden probability change exceeding your threshold
close_to_bond — probability approaching extreme levels (near 0% or 100%), signaling potential resolution
asset_price_tick — price update for a tracked asset
asset_price_window_update — price window metrics updated

Position events fire on position-level changes:

position_metrics — updated position metrics for tracked positions
position_volume_milestone — a position crosses a volume threshold
position_volume_spike — unusual volume on a specific position
event_volume_milestone — event-level volume milestone reached
event_volume_spike — unusual volume surge across an event group

The most compelling for most builders: trader_whale_trade for following smart money, probability_spike for catching price movements early, market_created for indexing new markets at launch, and close_to_bond for resolution alerts.

Filters: only get what matters

You don't subscribe to "all whale trades." You filter by wallet, minimum value, specific markets, tags, and 30+ other fields to get exactly the events you care about.

Whale trades above $10,000:

Event: trader_whale_trade with filter min_usd_value: 10000

Probability spikes on politics markets:

Event: probability_spike with filter tags: ["politics"]

Track a specific wallet's P&L:

Event: trader_global_pnl with filter wallet_addresses: ["0x7a3f...8b2c"]

Volume milestones above $1M:

Event: market_volume_milestone with filter milestone_amounts: [1000000]

Price movements above 5%:

Event: probability_spike with filter min_probability_change_pct: 5

Filters let you cut through the noise. Instead of receiving thousands of events and filtering client-side, you tell Struct exactly what matters and only receive events that match. Less bandwidth, less processing, more signal.

Setting up your first Polymarket webhook

Create a webhook with a single API call:

curl -X POST https://api.struct.to/v1/frontend/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "event": "trader_whale_trade",
    "description": "Whale trades above $10k",
    "secret": "your-signing-secret",
    "filters": {
      "min_usd_value": 10000
    }
  }'

When a matching event fires, your endpoint receives a POST request like this:

{
	"event": "trader_whale_trade",
	"timestamp": "2026-03-15T14:32:01Z",
	"data": {
		"market_name": "Will the Fed cut rates before July 2026?",
		"trader_address": "0x7a3f...8b2c",
		"side": "BUY",
		"size_usd": 85000,
		"price": 0.62,
		"probability_before": 0.58,
		"probability_after": 0.62
	}
}

Don't want to write code? The Struct dashboard lets you create, test, and manage webhooks with a visual interface. Select an event type, configure filters, paste your URL, and you're live.

You can also use the TypeScript SDK:

import Struct from "@structbuild/sdk";

const struct = new Struct({ apiKey: "YOUR_API_KEY" });

await struct.webhooks.create({
	url: "https://your-server.com/webhook",
	event: "trader_whale_trade",
	filters: { min_usd_value: 10000 },
});

Securing your webhooks

Every webhook payload Struct sends is signed with an HMAC-SHA256 signature using a secret you provide when creating the webhook. The signature is included in the X-Struct-Signature header.

Verify it on your server before processing any payload:

import crypto from "crypto";

function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean {
	const expected = crypto.createHmac("sha256", secret).update(payload).digest("hex");
	return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

const isValid = verifyWebhookSignature(rawBody, req.headers["x-struct-signature"], "your-signing-secret");

Always use timingSafeEqual to prevent timing attacks. Reject any request where the signature doesn't match.

Need to rotate your secret? You can do it via the API or the dashboard — no downtime, no webhook recreation required.

Use cases

Trading bots. React to probability_spike or trader_whale_trade events before the broader market catches up. A whale buys $85K of YES shares on a Fed rate decision market — your bot sees it instantly and adjusts positions.

Alert systems. Pipe trader_whale_trade and close_to_bond events to Discord or Telegram. Know the moment a market is about to resolve or a large position moves, without watching a screen.

Data pipelines. Subscribe to market_created and ingest every new market at launch. Build a complete research database that's always current, without polling for new markets.

AI agents. Feed webhook events to LLMs for real-time market analysis. A probability_spike fires, your agent pulls context from the Struct API, and posts an analysis explaining what just happened and why.

Portfolio tracking. Use trader_global_pnl and trader_market_pnl to monitor your own positions or track smart money in real time.

Struct also ships pre-built AI automations that combine webhooks with AI analysis — no code required:

Whale Trade Alert — a large position moves, AI reviews the trader's history and sends context to Discord
Price Spike Detective — sudden probability shift detected, AI explains what changed and why
New Market Analyzer — a new market goes live, AI summarises it and posts a trading assessment
Resolution Edge Tracker — a market approaches extreme probability, AI evaluates remaining edge

Each automation can deliver to Discord, Telegram, or any webhook endpoint.

Get started

The free tier includes full webhook access. Create an API key and set up your first webhook in under two minutes.

Get started at struct.to/dashboard Webhook docs at docs.struct.to TypeScript SDK on npm

Polymarket moves fast. Your infrastructure should move faster.