Skip to main content

​
Overview

polynode webhooks deliver real-time event notifications to your HTTP endpoint. Instead of polling the API, register a webhook and receive a POST request whenever matching events occur.
  • 16 event types covering trades, prices, markets, positions, and lifecycle events
  • Enriched payloads — every delivery includes market names, outcomes, slugs, and condition IDs
  • HMAC-SHA256 signed — verify every delivery with your webhook secret
  • 3-30 second polling — event cadence depends on the event type
  • Delivery transparency — full history of every delivery attempt, status code, and latency

​
Quick Start

​
1. Create a webhook

curl -X POST https://api.polynode.dev/v3/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/hooks/polymarket",
    "event_types": ["trade", "market_resolved"],
    "filters": {
      "wallet_addresses": ["0x6d3c5bd13984b2de47c3a88ddc455309aab3d294"],
      "min_amount_usd": 100
    },
    "description": "Track whale trades"
  }'

​
2. Receive deliveries

Every delivery is a POST to your URL with this structure: 
{
  "id": "evt_a60234f0-fe5d-4223-bc6a-75f1e4263eda",
  "type": "trade",
  "created_at": "2026-05-14T14:55:08.448161187+00:00",
  "data": {
    "maker": "0x6d3c5bd13984b2de47c3a88ddc455309aab3d294",
    "taker": "0xd5bba58c09d18f48a71a3aefc4ff3a66954c0fe1",
    "amount_usd": 39.99,
    "price": 0.81,
    "direction": "BUY",
    "market": "Will Al Fateh Saudi Club vs. Al Najmah Saudi Club end in a draw?",
    "slug": "spl-fat-njm-2026-05-14-draw",
    "outcome": "No",
    "condition_id": "0x3b7ad6a803daeb1994c840027b95d711d634e79a09ff3b02625600dc9d31a8bc",
    "event_slug": "spl-fat-njm-2026-05-14",
    "transaction_hash": "0x4f606b3d4c58c723e4aeb3051e3ba92100f9b0d9116e5d60f7668c34087c8167",
    "order_hash": "0x608029a5926da1fc3496ba08062c7e64f66b41a2c7383b5125f3867a68ca0b08",
    "builder": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "fee_usd": 0.0,
    "timestamp": "1778770502"
  }
}

​
3. Verify the signature

Every delivery includes HMAC-SHA256 headers: 
X-Webhook-ID: wh_451e06ca0534
X-Webhook-Event: trade
X-Webhook-Timestamp: 1778770328
X-Webhook-Signature: sha256=3357c641560d55fb46edccb85d3daad3c8099806b7d5d5f60088afb759c0db29
Verify with: 
import hmac, hashlib

expected = hmac.new(
    secret.encode(),
    f"{timestamp}.{body}".encode(),
    hashlib.sha256
).hexdigest()
assert hmac.compare_digest(f"sha256={expected}", signature_header)

​
Event Types

EventDescriptionPollingExclusive
tradeFill involving watched wallets or markets3s
large_tradeFill exceeding USD threshold3s
builder_tradeFill routed through a specific builder3spolynode only
first_tradeWallet’s first-ever Polymarket trade3s
price_changeToken price moves beyond threshold10s
market_resolvedMarket resolved with payouts10s
market_createdNew market appears30s
pnl_changeWallet PnL changes beyond threshold15s
position_status_changeWatched-wallet position opens/exits30spolynode only
redemptionWallet redeems shares15spolynode only
splitWallet splits conditional tokens15spolynode only
mergeWallet merges conditional tokens15spolynode only
neg_risk_conversionNeg-risk conversion event15spolynode only
fee_earnedFee receiver gets paid15spolynode only
wallet_activityAny action by a watched wallet3-15spolynode only
order_completeMulti-fill order finishes~33spolynode only
Events marked polynode only are exclusive to polynode — no other Polymarket data provider offers them.

​
Management API

MethodEndpointDescription
POST/v3/webhooksCreate webhook
GET/v3/webhooksList webhooks
GET/v3/webhooks/:idGet webhook
PUT/v3/webhooks/:idUpdate webhook
DELETE/v3/webhooks/:idDelete webhook
POST/v3/webhooks/:id/testSend test delivery
POST/v3/webhooks/:id/rotate-secretRotate secret
GET/v3/webhooks/:id/deliveriesDelivery history
GET/v3/webhooks/event-typesList event types

​
Retry Policy

AttemptDelay
1Immediate
210 seconds
360 seconds
45 minutes
51 hour
A delivery is successful if your endpoint returns HTTP 2xx within 5 seconds. Failed deliveries are visible in the delivery history endpoint.

​
Limits

TierMax WebhooksMax Deliveries/day
Starter1050,000
Pro50500,000
Enterprise500Unlimited