Webhooks - Codex

Webhooks deliver real-time updates from the Codex API directly to an HTTP endpoint you control. Unlike subscriptions, which require a persistent connection, webhooks fit naturally into event-driven architectures, alerting systems, and background services.

Delivery and retries

Codex sends webhook messages via HTTP POST and expects a 2xx response within 3 seconds. If your endpoint responds slowly or fails, the message will be retried up to two additional times with gradually increasing delays. If your service is down for long enough, some messages will be lost.

Webhook usage breakdown:

Processed means an event matched at a basic level (for example, maker, pair, or token address)
Triggered means all conditions passed and Codex will try to publish
Success means publishing was attempted and succeeded
Failed means publishing was attempted and failed (usually a bad URL)

Creating a webhook

The fastest way to create and test a webhook is through the Codex Explorer, which provides a visual builder for every supported event type. To create one programmatically, use the createWebhooks mutation. Each event type has its own input field on the mutation (for example, tokenPairEventWebhooksInput or predictionTradeWebhooksInput). See the event type sections below for a ready-to-use creation example for each.

Organizing webhooks with `bucketKey`

You can optionally group and query your webhooks using a bucketKey. This is useful when you are managing many webhooks per user or per token, such as a price alert system.

bucketKey: {
  bucketId: "price-alert-${user.id}"
  bucketSortKey: "price-alert-${token.id}"
}

Both bucketId and bucketSortKey must be provided together. If you don’t need to query webhooks by bucket, you can omit bucketKey entirely. Using both fields lets you independently query all alerts for a specific user and all alerts for a specific token.

The individual bucketId and bucketSortKey fields on createWebhook are deprecated. Use the bucketKey object instead.

Message structure

Every webhook message shares a common envelope. The type field tells you which event fired, and the data field contains the event-specific payload described in the event type sections.

type

WebhookPublisherMessageType

The event type. One of TOKEN_PAIR_EVENT, TOKEN_PAIR_EVENT_BATCH, TOKEN_PRICE_EVENT, TOKEN_PRICE_EVENT_BATCH, TOKEN_TRANSFER_EVENT, TOKEN_TRANSFER_EVENT_BATCH, MARKET_CAP_EVENT, MARKET_CAP_EVENT_BATCH, PREDICTION_TRADE_EVENT, PREDICTION_TRADE_EVENT_BATCH, PREDICTION_MARKET_METRICS_EVENT, or PREDICTION_MARKET_METRICS_EVENT_BATCH.

deduplicationId

String

A unique identifier for this message. Use it to deduplicate retries on your side.

webhookId

String

The ID of the webhook that triggered this message.

groupId

String

The ID used to group related messages for ordered delivery.

hash

String

deprecated

Deprecated. SHA256 hash of the securityToken and deduplicationId. Prefer the X-Webhook-Timestamp and X-Webhook-Signature headers described in Verifying webhooks. The legacy hash does not cover the request body and is still emitted only for backwards compatibility.

data

WebhookPublisherDataModels

The event-specific payload. The shape depends on type. See the event type sections for each payload structure.

Verifying webhooks

Every webhook delivery includes two signature headers that authenticate the exact request body bytes and provide a freshness signal for replay protection:

X-Webhook-Timestamp: Unix timestamp in seconds.
X-Webhook-Signature: lowercase hex HMAC-SHA256 over {timestamp}.{rawBody}, using your webhook’s securityToken as the key.

To verify a delivery:

Read the raw request body bytes as received, before any JSON parsing.
Build the signed payload string {timestamp}.{rawBody}.
Compute hex(hmac_sha256(securityToken, signedPayload)) and compare it to X-Webhook-Signature using a constant-time comparison.
Reject the request if abs(now - X-Webhook-Timestamp) > 300 seconds, or if either header is missing or malformed.

const crypto = require("crypto");

function verifyWebhook ({ rawBody, timestamp, signature, securityToken }) {
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (!Number.isFinite(age) || age > 300) {
    return false;
  }

  const expected = crypto
    .createHmac("sha256", securityToken)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const expectedBuffer = Buffer.from(expected, "hex");
  const signatureBuffer = Buffer.from(signature, "hex");

  return (
    expectedBuffer.length === signatureBuffer.length &&
    crypto.timingSafeEqual(expectedBuffer, signatureBuffer)
  );
}

Verify the original raw request body bytes, then parse JSON only after the signature check passes. Re-serializing the parsed body will change whitespace and key order and produce a different signature.

Capturing the raw body

Next.js App Router: call await request.text() once and use that exact string.
Next.js API routes: set export const config = { api: { bodyParser: false } }, then read the request stream into a buffer.
Express: mount express.raw({ type: "application/json" }) on the webhook route, or capture the buffer in express.json({ verify }).
AWS Lambda + API Gateway: use event.body directly, base64-decoding when event.isBase64Encoded is true.
Rails/Rack: use request.raw_post. Flask/Django: request.get_data() / request.body.

Common mistakes

Parsing and re-serializing JSON before verification.
Verifying only data or the legacy hash field instead of {timestamp}.{rawBody}.
Comparing signatures with == instead of a constant-time helper.
Treating the timestamp as milliseconds. X-Webhook-Timestamp is Unix seconds.
Skipping the freshness check, which removes replay protection.

Hash verification (deprecated)

The body hash field is deprecated. Use Verifying webhooks with X-Webhook-Timestamp and X-Webhook-Signature. The legacy hash is computed from sha256(securityToken + deduplicationId), so it only identifies the delivery id pair and does not authenticate the delivered body. Both the headers and the legacy hash are emitted during the migration period.

The legacy hash is a SHA256 digest of your webhook’s securityToken concatenated with the message’s deduplicationId:

const crypto = require('crypto');

const calculatedHash = crypto
  .createHash('sha256')
  .update(securityToken)
  .update(deduplicationId)
  .digest('hex');

Source IP addresses

Codex sends webhook deliveries from a fixed set of IP addresses. If you want to gate inbound webhook traffic at the network layer in addition to verifying the signature on each payload, allowlist these IPs at your firewall or load balancer:

155.50.173
25.29.13
235.164.143
32.112.191

Network-level allowlisting complements signature verification, it doesn’t replace it. Always verify the signature on incoming payloads to confirm authenticity.

Event types

Each event type fires on a different kind of on-chain or market activity. Pick the one that matches what you want to react to, then jump to its section below for filter conditions, the input field, a copy-paste mutation, and a sample payload.

Event	Fires when
Token Pair Event	Swaps, mints, burns, and other liquidity events on a trading pair. The most common type.
Token Price Event	A token’s price crosses a threshold you set.
Token Transfer Event	Tokens move to or from a wallet you’re watching.
Market Cap Event	A token’s market cap — fully diluted or circulating — crosses a threshold.
Prediction Trade Event	Individual Polymarket or Kalshi trades, filterable by trader, market, event, side, or size.
Prediction Market Metrics Event	A prediction market’s rolling windowed stats — volume, price, or trade count — cross a threshold, at the market or per-outcome level.

`TOKEN_PAIR_EVENT`

The TOKEN_PAIR_EVENT webhook fires when a swap, mint, burn, or other liquidity event occurs on a trading pair. It delivers the full Pair and Event objects so you can reconstruct exactly what happened on-chain. This is the most commonly used webhook. When to use it

Tracking every trade made by a specific wallet
Monitoring high-value swaps on a single token or pair
Feeding a live trade tape for a specific pool
Alerting on liquidity events (mints, burns) for a pair

Filter conditions

tokenAddress: fire for events involving this token
networkId: one or more network IDs to listen on
swapValue: filter by USD value of the swap
maker: fire for events made by a specific wallet
pairAddress: fire for events on a specific pair
exchangeAddress: fire for events on a specific exchange
eventType: filter to specific event types (SWAP, MINT, BURN, SYNC, BUY, SELL, COLLECT, COLLECT_PROTOCOL)

See the full input type at tokenPairEventWebhookConditionInput.

Creation example

mutation CreateTokenPairWebhook {
  createWebhooks(
    input: {
      tokenPairEventWebhooksInput: {
        webhooks: {
          name: "Big swaps on WETH/USDC"
          callbackUrl: "https://your-endpoint.com/webhook"
          securityToken: "your-security-token"
          alertRecurrence: INDEFINITE
          conditions: {
            pairAddress: { eq: "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640" }
            networkId: { oneOf: [1] }
            swapValue: { gte: "10000" }
          }
        }
      }
    }
  ) {
    tokenPairEventWebhooks {
      id
      name
    }
  }
}

Message payload

{
  "deduplicationId": "aa4cd403-b54e-4e2d-825c-f70a69f6fd9f-DbyEjKTHE76qgb8niQ4zDCoaU4CK7Si9PJkD6Ckjtugo:1399811149-0000000256717997#00000000#00000002#00000009",
  "groupId": "bc9345e6-b0da-4935-9b31-47b34cc5f628",
  "hash": "e39fa0bfcef1bfcd12d6707c29ac752899228d026338e594e04a398255962022",
  "type": "TOKEN_PAIR_EVENT",
  "webhook": {
    "bucketId": "bc9345e6-b0da-4935-9b31-47b34cc5f628",
    "bucketSortkey": "GSE6vfr6vws493G22jfwCU6Zawh3dfvSYXYQqKhFsBwe",
    "id": "aa4cd403-b54e-4e2d-825c-f70a69f6fd9f",
    "name": "traderpow:GSE6vfr6vws493G22jfwCU6Zawh3dfvSYXYQqKhFsBwe:TOKEN_PAIR_EVENT"
  },
  "webhookId": "aa4cd403-b54e-4e2d-825c-f70a69f6fd9f",
  "data": {
    "event": {
      "address": "DbyEjKTHE76qgb8niQ4zDCoaU4CK7Si9PJkD6Ckjtugo",
      "baseTokenPrice": "18651403264.31996",
      "blockHash": "DGXgkMSxovvjdA5iKgrsFL7duNyXRPsW86Ztvg2Mc1hL",
      "blockNumber": 256717997,
      "data": {
        "amount0": "7020307392",
        "amount1": "-2899270904078",
        "liquidity": "51478999661589",
        "liquidity0": "1140722809229",
        "liquidity1": "457845387792910",
        "protocol": "Orca",
        "sqrtPriceX64": "376244087403309877755",
        "tick": "60310",
        "type": "Swap"
      },
      "eventDisplayType": "Buy",
      "eventType": "Swap",
      "eventType2": "Token1Buy",
      "id": "DbyEjKTHE76qgb8niQ4zDCoaU4CK7Si9PJkD6Ckjtugo:1399811149",
      "labels": {},
      "liquidityToken": "So11111111111111111111111111111111111111112",
      "logIndex": 2,
      "maker": "GSE6vfr6vws493G22jfwCU6Zawh3dfvSYXYQqKhFsBwe",
      "makerHashKey": "GSE6vfr6vws493G22jfwCU6Zawh3dfvSYXYQqKhFsBwe:DbyEjKTHE76qgb8niQ4zDCoaU4CK7Si9PJkD6Ckjtugo:1399811149",
      "networkId": 1399811149,
      "quoteToken": "token1",
      "sortKey": "0000000256717997#00000000#00000002#00000009",
      "supplementalIndex": 9,
      "timestamp": 1711526246,
      "token0PoolValueUsd": "186.5140326431996",
      "token0SwapValueUsd": "186.51403264319955960744460600963952776157867455426636901017",
      "token0ValueBase": "1",
      "token0ValueUsd": "186.5140326431996",
      "token1PoolValueUsd": "0.4483442346979745",
      "token1SwapValueUsd": "0.45162590368325119780671230665069180443756818839541768",
      "token1ValueBase": "0.0024038096669951625071971972244735217782",
      "token1ValueUsd": "0.4483442346979745",
      "transactionHash": "2dd5jDHbVYZpXgYbEQzpv47Z7jwimmHeDxKytiM9FB4GzBA5QeYh5xHTzkQvCScQksvTrHqgq9k7q84MBcGbaFfJ",
      "transactionIndex": 0,
      "ttl": 1716710246
    },
    "pair": {
      "address": "DbyEjKTHE76qgb8niQ4zDCoaU4CK7Si9PJkD6Ckjtugo",
      "exchangeHash": "whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc",
      "fee": null,
      "id": "DbyEjKTHE76qgb8niQ4zDCoaU4CK7Si9PJkD6Ckjtugo:1399811149",
      "networkId": 1399811149,
      "tickSpacing": null,
      "token0": "So11111111111111111111111111111111111111112",
      "token1": "FU1q8vJpZNUrmqsciSjp8bAKKidGsLmouB8CBdf8TKQv"
    }
  }
}

## BATCH VERSION
{
  "deduplicationId": "aa4cd403-b54e-4e2d-825c-f70a69f6fd9f-batch-0000000256717997",
  "groupId": "bc9345e6-b0da-4935-9b31-47b34cc5f628",
  "hash": "e39fa0bfcef1bfcd12d6707c29ac752899228d026338e594e04a398255962022",
  "type": "TOKEN_PAIR_EVENT_BATCH",
  "webhookId": "aa4cd403-b54e-4e2d-825c-f70a69f6fd9f",
  "data": [
    {
      "event": { "...": "same shape as single event above" },
      "pair": { "...": "same shape as single event above" }
    },
    {
      "event": { "...": "second event in batch" },
      "pair": { "...": "second pair in batch" }
    }
  ]
}

`TOKEN_PRICE_EVENT`

The TOKEN_PRICE_EVENT webhook fires when the price of a specific token crosses a threshold you define. Use it for price alerts on tokens you care about. When to use it

Price alerts for a single token (for example, “WETH above $4000”)
Watchlist-style notifications for a small set of tokens
Dashboard price tickers where polling is not acceptable

Filter conditions

address: the token contract address (required)
networkId: the network ID (required)
priceUsd: price condition that must be met (required). Supports gt, gte, lt, lte, eq

See the full input type at tokenPriceEventWebhookConditionInput.

Creation example

mutation CreateTokenPriceWebhook {
  createWebhooks(
    input: {
      priceWebhooksInput: {
        webhooks: {
          name: "WETH above $4000"
          callbackUrl: "https://your-endpoint.com/webhook"
          securityToken: "your-security-token"
          alertRecurrence: INDEFINITE
          conditions: {
            address: { eq: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" }
            networkId: { eq: 1 }
            priceUsd: { gte: "4000" }
          }
        }
      }
    }
  ) {
    priceWebhooks {
      id
      name
    }
  }
}

Message payload

{
  "type": "TOKEN_PRICE_EVENT",
  "deduplicationId": "5e0fe797-c795-451f-af87-0257847b8c3b-0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2:1-0000000024000071#00000117#00000353",
  "webhookId": "5e0fe797-c795-451f-af87-0257847b8c3b",
  "groupId": "5e0fe797-c795-451f-af87-0257847b8c3b",
  "hash": "c296a760c563c9a4115146af75945d1b35d0741835309fa44d393ef3c2b044dd",
  "webhook": {
    "id": "5e0fe797-c795-451f-af87-0257847b8c3b",
    "name": "token-price-webhook"
  },
  "data": {
    "id": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2:1",
    "priceUsd": "3.0898058248076381750556910457327e+3",
    "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "networkId": 1,
    "timestamp": 1765585223,
    "blockNumber": 24000071
  }
}

## BATCH VERSION
{
  "type": "TOKEN_PRICE_EVENT_BATCH",
  "deduplicationId": "5e0fe797-c795-451f-af87-0257847b8c3b-batch-0000000024000071",
  "webhookId": "5e0fe797-c795-451f-af87-0257847b8c3b",
  "groupId": "5e0fe797-c795-451f-af87-0257847b8c3b",
  "hash": "c296a760c563c9a4115146af75945d1b35d0741835309fa44d393ef3c2b044dd",
  "data": [
    { "...": "same shape as the single message above" },
    { "...": "additional messages in the batch" }
  ]
}

`TOKEN_TRANSFER_EVENT`

The TOKEN_TRANSFER_EVENT webhook fires when a token is transferred to or from a wallet you are monitoring. Use it to track wallet inflows and outflows in real time. When to use it

Monitoring whale wallet movements
Triggering on-chain alerts for your own wallets
Watching known exchange hot wallets or bridge addresses

Filter conditions

tokenAddress: the token contract to track
networkId: one or more network IDs
address: the wallet address to monitor
direction: TO (receiving), FROM (sending), or both

See the full input type at tokenTransferEventWebhookConditionInput.

Creation example

mutation CreateTokenTransferWebhook {
  createWebhooks(
    input: {
      tokenTransferEventWebhooksInput: {
        webhooks: {
          name: "Inflows to whale wallet"
          callbackUrl: "https://your-endpoint.com/webhook"
          securityToken: "your-security-token"
          alertRecurrence: INDEFINITE
          conditions: {
            address: { eq: "0x1abde2088657de84ad6239f3d445dd07d6fa1033" }
            networkId: { oneOf: [8453] }
            direction: { oneOf: [TO] }
          }
        }
      }
    }
  ) {
    tokenTransferEventWebhooks {
      id
      name
    }
  }
}

Message payload

{
  "type": "TOKEN_TRANSFER_EVENT",
  "deduplicationId": "6af3a260-7e2c-4615-babe-c239786ec9fd-0x84df029b0fc5d81ec8d65fa49568bc509e8ce0caa3de05c8de51acea8aafdb6b-740",
  "webhookId": "6af3a260-7e2c-4615-babe-c239786ec9fd",
  "groupId": "762acfb9-872d-4fa7-96a0-e45236759c55",
  "hash": "360adec82a811049a7374b087c40789e716c2329cb5dfc9b6dffc182fb77cd2b",
  "webhook": {
    "id": "6af3a260-7e2c-4615-babe-c239786ec9fd",
    "name": "Track transfers to wallet"
  },
  "data": {
    "tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "networkId": 8453,
    "fromAddress": "0x4767bf3619bb493d129c864a023512fa1dce9da4",
    "toAddress": "0x1abde2088657de84ad6239f3d445dd07d6fa1033",
    "amount": "20000",
    "shiftedAmount": "0.02",
    "direction": "TO",
    "timestamp": 1767657659,
    "blockNumber": 40434156,
    "transactionHash": "0x84df029b0fc5d81ec8d65fa49568bc509e8ce0caa3de05c8de51acea8aafdb6b",
    "transactionIndex": 171,
    "logIndex": 740
  }
}

## BATCH VERSION
{
  "type": "TOKEN_TRANSFER_EVENT_BATCH",
  "deduplicationId": "6af3a260-7e2c-4615-babe-c239786ec9fd-batch-40434156",
  "webhookId": "6af3a260-7e2c-4615-babe-c239786ec9fd",
  "groupId": "762acfb9-872d-4fa7-96a0-e45236759c55",
  "hash": "360adec82a811049a7374b087c40789e716c2329cb5dfc9b6dffc182fb77cd2b",
  "webhook": {
    "id": "6af3a260-7e2c-4615-babe-c239786ec9fd",
    "name": "Track all transfers"
  },
  "data": [
    { "...": "same shape as the single message above" },
    { "...": "additional messages in the batch" }
  ]
}

`MARKET_CAP_EVENT`

The MARKET_CAP_EVENT webhook fires when a token’s market cap crosses a threshold you specify. Unlike token price webhooks, it factors in supply (both fully diluted and circulating). When to use it

Market cap milestone alerts (for example, “VIRTUAL crosses $1B FDV”)
Large-cap filtering logic for automated tools
Portfolio-level risk dashboards

Filter conditions

tokenAddress: the token contract (required)
networkId: the network ID (required)
fdvMarketCapUsd: fully diluted market cap threshold
circulatingMarketCapUsd: circulating market cap threshold
pairAddress: optional source pair constraint
liquidityUsd, volumeUsd: optional pair-level liquidity and volume constraints

See the full input type at marketCapEventWebhookConditionInput.

Creation example

mutation CreateMarketCapWebhook {
  createWebhooks(
    input: {
      marketCapEventWebhooksInput: {
        webhooks: {
          name: "VIRTUAL hits $1B FDV"
          callbackUrl: "https://your-endpoint.com/webhook"
          securityToken: "your-security-token"
          alertRecurrence: ONCE
          conditions: {
            tokenAddress: { eq: "0x0b3e328455c4059eeb9e3f84b5543f74e24e7e1b" }
            networkId: { eq: 8453 }
            fdvMarketCapUsd: { gte: "1000000000" }
          }
        }
      }
    }
  ) {
    marketCapEventWebhooks {
      id
      name
    }
  }
}

Message payload

{
  "type": "MARKET_CAP_EVENT",
  "deduplicationId": "5e0fe797-c795-451f-af87-0257847b8c3b-0x0b3e328455c4059eeb9e3f84b5543f74e24e7e1b:8453-0000000030917440#00000117#00000353",
  "webhookId": "5e0fe797-c795-451f-af87-0257847b8c3b",
  "groupId": "test-group",
  "hash": "c296a760c563c9a4115146af75945d1b35d0741835309fa44d393ef3c2b044dd",
  "webhook": {
    "id": "5e0fe797-c795-451f-af87-0257847b8c3b",
    "name": "mcap-virt"
  },
  "data": {
    "priceModel": {
      "id": "0x0b3e328455c4059eeb9e3f84b5543f74e24e7e1b:8453",
      "priceUsd": "2.014904011469267",
      "address": "0x0b3e328455c4059eeb9e3f84b5543f74e24e7e1b",
      "networkId": 8453,
      "timestamp": 1748624227,
      "blockNumber": 30917440,
      "absoluteDeviation": 0,
      "derivedSwapPrice": "2.008965143151456",
      "targetTokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "pairMetadata": {
        "liquidityUsd": "67747",
        "pairId": "0x2aeee741fa1e21120a21e57db9ee545428e683c9:1",
        "volume24Usd": "162206"
      }
    },
    "tokenModel": {
      "id": "0x0b3e328455c4059eeb9e3f84b5543f74e24e7e1b:8453",
      "address": "0x0b3e328455c4059eeb9e3f84b5543f74e24e7e1b",
      "name": "Virtual Protocol",
      "symbol": "VIRTUAL",
      "decimals": 18,
      "shiftedTotalSupply": "495620931.12225886540849246",
      "shiftedCirculatingSupply": "495620930.505466750752879695"
    },
    "fdvMarketCapUsd": "998628602.29",
    "circulatingMarketCapUsd": "998628601.04"
  }
}

## BATCH VERSION
{
  "type": "MARKET_CAP_EVENT_BATCH",
  "deduplicationId": "5e0fe797-c795-451f-af87-0257847b8c3b-batch-0000000030917440",
  "webhookId": "5e0fe797-c795-451f-af87-0257847b8c3b",
  "groupId": "test-group",
  "hash": "c296a760c563c9a4115146af75945d1b35d0741835309fa44d393ef3c2b044dd",
  "data": [
    {
      "priceModel": { "...": "same shape as single event above" },
      "tokenModel": { "...": "same shape as single event above" },
      "fdvMarketCapUsd": "998628602.29",
      "circulatingMarketCapUsd": "998628601.04"
    }
  ]
}

`PREDICTION_TRADE_EVENT`

The PREDICTION_TRADE_EVENT webhook fires when a prediction market trade occurs. Use it to track trades by a specific trader, on a specific market or event, or matching conditions like trade value or volume. When to use it

Tracking copy-traded wallets on Polymarket or Kalshi
Notifying on large trades in a specific market or event
Feeding a live trade tape for a prediction market dashboard

Filter conditions

traderId: fire for a specific trader
marketId: fire for a specific market
eventId: fire for a specific event
eventType: filter by trade event type (TRADE, BUY, SELL, BUY_COUNTERPARTY, SELL_COUNTERPARTY, PAYOUT_REDEMPTION)
tradeValueUsd: filter by trade value in USD
amountToken: filter by number of tokens or shares traded

See the full input type at predictionTradeWebhookConditionInput.

Creation example

mutation CreatePredictionTradeWebhook {
  createWebhooks(
    input: {
      predictionTradeWebhooksInput: {
        webhooks: {
          name: "Track trader activity"
          callbackUrl: "https://your-endpoint.com/webhook"
          securityToken: "your-security-token"
          alertRecurrence: INDEFINITE
          conditions: {
            traderId: { eq: "your-trader-id" }
            tradeValueUsd: { gte: "100" }
          }
          bucketKey: {
            bucketId: "trader-alerts-${user.id}"
            bucketSortKey: "trader-${traderId}"
          }
        }
      }
    }
  ) {
    predictionTradeWebhooks {
      id
      name
    }
  }
}

Message payload

{
  "type": "PREDICTION_TRADE_EVENT",
  "deduplicationId": "abc123-...",
  "webhookId": "6af3a260-7e2c-4615-babe-c239786ec9fd",
  "groupId": "762acfb9-872d-4fa7-96a0-e45236759c55",
  "hash": "360adec82a811049a7374b087c40789e716c2329cb5dfc9b6dffc182fb77cd2b",
  "webhook": {
    "id": "6af3a260-7e2c-4615-babe-c239786ec9fd",
    "name": "Track trader activity"
  },
  "data": {
    "marketId": "0x1234...abcd",
    "sortKey": "0000000040434156#00000171#00000740",
    "outcomeId": "outcome-1",
    "outcomeLabel": "Yes",
    "protocol": "POLYMARKET",
    "tradeType": "BUY",
    "maker": "0x4767bf3619bb493d129c864a023512fa1dce9da4",
    "timestamp": 1767657659,
    "outcomeIndex": 0,
    "priceUsd": "0.72",
    "priceCollateral": "0.72",
    "amount": "100",
    "amountCollateral": "72",
    "amountUsd": "72.00",
    "transactionHash": "0x84df029b0fc5d81ec8d65fa49568bc509e8ce0caa3de05c8de51acea8aafdb6b",
    "blockNumber": 40434156,
    "networkId": 137,
    "exchangeAddress": "0xe55b5ceba4dc0d4e26261f3dcd468faaf7d0cdb8",
    "transactionId": "txn-abc123",
    "traderId": "trader-xyz",
    "eventId": "event-456"
  }
}

## BATCH VERSION
{
  "type": "PREDICTION_TRADE_EVENT_BATCH",
  "deduplicationId": "abc123-batch-40434156",
  "webhookId": "6af3a260-7e2c-4615-babe-c239786ec9fd",
  "groupId": "762acfb9-872d-4fa7-96a0-e45236759c55",
  "hash": "360adec82a811049a7374b087c40789e716c2329cb5dfc9b6dffc182fb77cd2b",
  "data": [
    { "...": "same shape as the single message above" },
    { "...": "additional messages in the batch" }
  ]
}

`PREDICTION_MARKET_METRICS_EVENT`

The PREDICTION_MARKET_METRICS_EVENT webhook fires when rolling, windowed statistics for a prediction market cross a threshold you define — at the whole-market level or for an individual outcome. Use it to react to volume spikes, price moves, or bursts of trading activity on a Polymarket or Kalshi market without polling. When to use it

Alerting on volume or trade-count spikes on a specific market
Tracking a price move on a single outcome (for example, “Yes” climbing past 60%)
Driving a live activity feed for a prediction market dashboard

Filter conditions Metrics are evaluated over rolling time windows. Each window is its own field: min5, hour1, hour4, hour12, day1, and week1. Set a condition on one or more windows, and within a window match on:

Market-level metrics (the market field): volumeUsd, trades, volumeChange, tradesChange
Per-outcome metrics (outcome0, outcome1, or anyOutcome): everything available at the market level plus price and priceChange

marketId is required — each webhook is pinned to a single market. Every metric supports the standard gt, gte, lt, lte, and eq operators. See the full input type at predictionMarketMetricsEventWebhookConditionInput.

Creation example

mutation CreatePredictionMarketMetricsWebhook {
  createWebhooks(
    input: {
      predictionMarketMetricsEventWebhooksInput: {
        webhooks: {
          name: "Volume spike on a prediction market"
          callbackUrl: "https://your-endpoint.com/webhook"
          securityToken: "your-security-token"
          alertRecurrence: INDEFINITE
          conditions: {
            marketId: { eq: "your-market-id" }
            market: {
              hour1: {
                volumeUsd: { gte: "50000" }
                tradesChange: { gte: "2" }
              }
            }
            anyOutcome: {
              hour1: { priceChange: { gte: "0.1" } }
            }
          }
        }
      }
    }
  ) {
    predictionMarketMetricsEventWebhooks {
      id
      name
    }
  }
}

Message payload

Deliveries use the standard message envelope. The data object carries the market, its lifecycle, one block per rolling window (statsMin5, statsHour1, statsHour4, statsHour12, statsDay1, statsWeek1), and trending / relevance / competitive score series. Each window holds market-level core totals, outcome0Stats / outcome1Stats (price, volume, orderbook), and a statsChange block whose volumeChange, tradesChange, and priceChange ratios are what your filter conditions compare against. The example shows the min5 window in full; the other windows share the same shape.

{
  "type": "PREDICTION_MARKET_METRICS_EVENT",
  "deduplicationId": "103cb449-9165-442c-a94e-4e2394191096:KXATPMATCH-26JUN01TIAARN-ARN:Kalshi:1780339453",
  "webhookId": "103cb449-9165-442c-a94e-4e2394191096",
  "groupId": "default",
  "hash": "5f8fe57bd7ed36aa04237112cdaba68b04568b734a4f0cf7dd43ed26a5b934bd",
  "webhook": {
    "id": "103cb449-9165-442c-a94e-4e2394191096",
    "name": "Any"
  },
  "data": {
    "marketId": "KXATPMATCH-26JUN01TIAARN-ARN:Kalshi",
    "lastTransactionAt": 1780339453,
    "lifecycle": {
      "ageSeconds": 158894,
      "expectedLifespanSeconds": 1333440,
      "timeToResolutionSeconds": 1174546,
      "isResolved": false
    },
    "statsMin5": {
      "start": 1780339140,
      "end": 1780339500,
      "lastTransactionAt": 1780339453,
      "core": {
        "volume": { "usd": "214790", "ct": "214790" },
        "trades": 344
      },
      "uniqueTraders": null,
      "liquidity": null,
      "openInterest": {
        "openInterest": {
          "open": { "usd": "2511700", "ct": "2511700" },
          "close": { "usd": "2880725", "ct": "2880725" },
          "low": { "usd": "2511700", "ct": "2511700" },
          "high": { "usd": "2880725", "ct": "2880725" }
        }
      },
      "outcome0Stats": {
        "core": {
          "venueOutcomeId": "yes#KXATPMATCH-26JUN01TIAARN-ARN:Kalshi",
          "trades": 282,
          "volume": { "usd": "205033", "ct": "205033", "shares": "398508360000" },
          "price": {
            "open": { "usd": "0.52", "ct": "0.52" },
            "close": { "usd": "0.6", "ct": "0.6" },
            "low": { "usd": "0.5", "ct": "0.5" },
            "high": { "usd": "0.6", "ct": "0.6" }
          }
        },
        "buySell": null,
        "liquidity": null,
        "orderbook": {
          "bid": {
            "open": { "usd": "0", "ct": "0" },
            "close": { "usd": "0", "ct": "0" },
            "low": { "usd": "0", "ct": "0" },
            "high": { "usd": "0", "ct": "0" }
          },
          "ask": {
            "open": { "usd": "0.56", "ct": "0.56" },
            "close": { "usd": "0.6", "ct": "0.6" },
            "low": { "usd": "0.5", "ct": "0.5" },
            "high": { "usd": "0.6", "ct": "0.6" }
          }
        },
        "depth": null,
        "statsChange": {
          "volumeChange": 1.1353822760552819,
          "volumeSharesChange": 1.1420015657514841,
          "priceChange": 0.17647058823529413,
          "tradesChange": 0.128,
          "priceRange": 0.18181818181818182
        }
      },
      "outcome1Stats": { "...": "same shape as outcome0Stats, for the 'no' outcome" },
      "allTimeStats": {
        "volume": { "usd": "1862439", "ct": "1862439" },
        "venueVolume": { "usd": "3478959", "ct": "3478959" }
      },
      "statsChange": {
        "volumeChange": 0.7787107886978701,
        "tradesChange": -0.13784461152882205,
        "openInterestChange": 0.10838253428676413
      },
      "scores": {
        "trending": 0.5129627015063644,
        "relevance": 0.9802115747563149,
        "competitive": 0.7098313166349453
      }
    },
    "statsHour1": { "...": "same shape as statsMin5, for the 1h window" },
    "statsHour4": { "...": "same shape as statsMin5, for the 4h window" },
    "statsHour12": { "...": "same shape as statsMin5, for the 12h window" },
    "statsDay1": { "...": "same shape as statsMin5, for the 24h window" },
    "statsWeek1": { "...": "same shape as statsMin5, for the 1w window" },
    "trendingScores": {
      "score5m": 0.5129627015063644,
      "score1": 0.5526402920243513,
      "score4": 0.6330336268045679,
      "score12": 0.6056772499786226,
      "score24": 0.7080148356575182,
      "score1w": 0.49798763786971245
    },
    "relevanceScores": {
      "score5m": 0.9802115747563149,
      "score1": 0.9802115747563149,
      "score4": 0.9802115747563149,
      "score12": 0.9802115747563149,
      "score24": 0.9802115747563149,
      "score1w": 0.9506551892542483
    },
    "competitiveScores": {
      "score5m": 0.7098313166349453,
      "score1": 0.8411082705350258,
      "score4": 0.8190846252610525,
      "score12": 0.8288629254817336,
      "score24": 0.8254551774444506,
      "score1w": 0.8253162265343478
    },
    "allTimeStats": {
      "volume": { "usd": "1862439", "ct": "1862439" },
      "venueVolume": { "usd": "3478959", "ct": "3478959" }
    },
    "eventId": "KXATPMATCH-26JUN01TIAARN:Kalshi"
  }
}

FAQ

How many tokens can I add to a single webhook?

Webhooks monitor one token at a time, but there is no limit on how many webhooks you can create. To watch many tokens, create one webhook per token (the bucketKey field makes managing large sets straightforward).

How do I push real-time buys via webhooks?

Create a TOKEN_PAIR_EVENT webhook for the token and filter eventType to BUY. The webhook payload includes the full event object, so you don’t need a follow-up call to enrich the data. See the TOKEN_PAIR_EVENT section above for the full creation example.

What is the `securityToken` field for, and how do I verify it?

securityToken is your secret. Codex uses it as the HMAC key for the X-Webhook-Signature header on every delivery, which authenticates the exact raw request body. See Verifying webhooks for the full verification flow. The legacy body hash field is also derived from securityToken but is deprecated because it doesn’t cover the body.

How is webhook usage measured against my plan's monthly request limit?

Each webhook delivery counts as 1 request. If you also fire a follow-up API call to enrich the event (e.g. fetching token metadata), that’s a second request. So if you’re processing 10k buys per day with one enrichment call each, that’s 20k requests/day or roughly 600k/month.

​Delivery and retries

​Creating a webhook

​Organizing webhooks with bucketKey

​Message structure

​Verifying webhooks

​Hash verification (deprecated)

​Source IP addresses

​Event types

​TOKEN_PAIR_EVENT

​TOKEN_PRICE_EVENT

​TOKEN_TRANSFER_EVENT

​MARKET_CAP_EVENT

​PREDICTION_TRADE_EVENT

​PREDICTION_MARKET_METRICS_EVENT

​FAQ

Delivery and retries

Creating a webhook

Organizing webhooks with `bucketKey`

Message structure

Verifying webhooks

Hash verification (deprecated)

Source IP addresses

Event types

`TOKEN_PAIR_EVENT`

`TOKEN_PRICE_EVENT`

`TOKEN_TRANSFER_EVENT`

`MARKET_CAP_EVENT`

`PREDICTION_TRADE_EVENT`

`PREDICTION_MARKET_METRICS_EVENT`

FAQ