> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codex.io/llms.txt
> Use this file to discover all available pages before exploring further.
# createWebhooks
> Create event webhooks for price, token/pair, transfer, market cap, and prediction market trades.
## GraphQL
```
type Mutation {
# Requires a Growth or Enterprise plan.
createWebhooks(
input: CreateWebhooksInput!
): CreateWebhooksOutput!
}
enum WebhookType {
PRICE_EVENT
TOKEN_PAIR_EVENT
RAW_TRANSACTION
MARKET_CAP_EVENT
TOKEN_PRICE_EVENT
TOKEN_TRANSFER_EVENT
PREDICTION_TRADE
PREDICTION_MARKET_METRICS_EVENT
}
enum AlertRecurrence {
INDEFINITE
ONCE
}
type StringEqualsCondition {
eq: String!
}
type IntEqualsCondition {
eq: Int!
}
type ComparisonOperator {
gt: String
gte: String
lt: String
lte: String
eq: String
}
type PriceEventWebhookCondition {
tokenAddress: StringEqualsCondition!
networkId: IntEqualsCondition!
priceUsd: ComparisonOperator!
pairAddress: StringEqualsCondition
liquidityUsd: ComparisonOperator
volumeUsd: ComparisonOperator
}
type MarketCapEventWebhookCondition {
tokenAddress: StringEqualsCondition!
networkId: IntEqualsCondition!
fdvMarketCapUsd: ComparisonOperator
circulatingMarketCapUsd: ComparisonOperator
pairAddress: StringEqualsCondition
liquidityUsd: ComparisonOperator
volumeUsd: ComparisonOperator
}
type OneOfNumberCondition {
oneOf: [Int!]!
}
enum TokenPairEventType {
SWAP
MINT
BURN
SYNC
BUY
SELL
COLLECT
COLLECT_PROTOCOL
}
type TokenPairEventTypeCondition {
oneOf: [TokenPairEventType!]!
}
type TokenPairEventWebhookCondition {
tokenAddress: StringEqualsCondition
networkId: OneOfNumberCondition
swapValue: ComparisonOperator
maker: StringEqualsCondition
pairAddress: StringEqualsCondition
exchangeAddress: StringEqualsCondition
eventType: TokenPairEventTypeCondition
}
type StringContainsCondition {
contains: [String!]
notContains: [String!]
}
type RawTransactionWebhookCondition {
networkId: OneOfNumberCondition
to: StringEqualsCondition
from: StringEqualsCondition
toOrFrom: StringEqualsCondition
input: StringContainsCondition
ignoreTokenPairEvents: Boolean
}
type TokenPriceEventWebhookCondition {
address: StringEqualsCondition!
networkId: IntEqualsCondition!
priceUsd: ComparisonOperator!
}
enum TokenTransferDirection {
FROM
TO
}
type OneOfTokenTransferDirectionCondition {
oneOf: [TokenTransferDirection!]!
}
type TokenTransferEventWebhookCondition {
tokenAddress: StringEqualsCondition
networkId: OneOfNumberCondition
address: StringEqualsCondition
direction: OneOfTokenTransferDirectionCondition
}
enum PredictionTradeEventType {
TRADE
BUY
SELL
BUY_COUNTERPARTY
SELL_COUNTERPARTY
POSITION_REDEEMED
}
type PredictionTradeEventTypeCondition {
oneOf: [PredictionTradeEventType!]!
}
type PredictionTradeWebhookCondition {
traderId: StringEqualsCondition
marketId: StringEqualsCondition
eventId: StringEqualsCondition
eventType: PredictionTradeEventTypeCondition
tradeValueUsd: ComparisonOperator
amountToken: ComparisonOperator
}
type WindowedPredictionMarketMetricsEventMarketCondition {
volumeUsd: ComparisonOperator
trades: ComparisonOperator
volumeChange: ComparisonOperator
tradesChange: ComparisonOperator
}
type PredictionMarketMetricsEventMarketCondition {
min5: WindowedPredictionMarketMetricsEventMarketCondition
hour1: WindowedPredictionMarketMetricsEventMarketCondition
hour4: WindowedPredictionMarketMetricsEventMarketCondition
hour12: WindowedPredictionMarketMetricsEventMarketCondition
day1: WindowedPredictionMarketMetricsEventMarketCondition
week1: WindowedPredictionMarketMetricsEventMarketCondition
}
type WindowedPredictionMarketMetricsEventOutcomeCondition {
price: ComparisonOperator
priceChange: ComparisonOperator
volumeUsd: ComparisonOperator
volumeChange: ComparisonOperator
trades: ComparisonOperator
tradesChange: ComparisonOperator
}
type PredictionMarketMetricsEventOutcomeCondition {
min5: WindowedPredictionMarketMetricsEventOutcomeCondition
hour1: WindowedPredictionMarketMetricsEventOutcomeCondition
hour4: WindowedPredictionMarketMetricsEventOutcomeCondition
hour12: WindowedPredictionMarketMetricsEventOutcomeCondition
day1: WindowedPredictionMarketMetricsEventOutcomeCondition
week1: WindowedPredictionMarketMetricsEventOutcomeCondition
}
type PredictionMarketMetricsEventWebhookCondition {
marketId: StringEqualsCondition!
market: PredictionMarketMetricsEventMarketCondition
outcome0: PredictionMarketMetricsEventOutcomeCondition
outcome1: PredictionMarketMetricsEventOutcomeCondition
anyOutcome: PredictionMarketMetricsEventOutcomeCondition
}
union WebhookCondition = PriceEventWebhookCondition | MarketCapEventWebhookCondition | TokenPairEventWebhookCondition | RawTransactionWebhookCondition | TokenPriceEventWebhookCondition | TokenTransferEventWebhookCondition | PredictionTradeWebhookCondition | PredictionMarketMetricsEventWebhookCondition
type RetrySettings {
maxTimeElapsed: Int
minRetryDelay: Int
maxRetryDelay: Int
maxRetries: Int
}
enum PublishingType {
BATCH
SINGLE
}
type Webhook {
id: String!
webhookType: WebhookType!
name: String!
created: Int!
alertRecurrence: AlertRecurrence!
callbackUrl: String!
status: String!
conditions: WebhookCondition!
retrySettings: RetrySettings
bucketId: String
bucketSortkey: String
publishingType: PublishingType
}
type CreateWebhooksOutput {
priceWebhooks: [Webhook]!
tokenPairEventWebhooks: [Webhook]!
rawTransactionWebhooks: [Webhook]!
marketCapWebhooks: [Webhook]!
tokenPriceEventWebhooks: [Webhook]!
tokenTransferEventWebhooks: [Webhook]!
predictionTradeWebhooks: [Webhook]!
predictionMarketMetricsEventWebhooks: [Webhook]!
}
input StringEqualsConditionInput {
eq: String!
}
input IntEqualsConditionInput {
eq: Int!
}
input ComparisonOperatorInput {
gt: String
gte: String
lt: String
lte: String
eq: String
}
input PriceEventWebhookConditionInput {
tokenAddress: StringEqualsConditionInput!
networkId: IntEqualsConditionInput!
priceUsd: ComparisonOperatorInput!
pairAddress: StringEqualsConditionInput
volumeUsd: ComparisonOperatorInput
liquidityUsd: ComparisonOperatorInput
}
input RetrySettingsInput {
maxTimeElapsed: Int
minRetryDelay: Int
maxRetryDelay: Int
maxRetries: Int
}
input BucketKeyInput {
bucketId: String!
bucketSortKey: String!
}
input CreatePriceWebhookArgs {
name: String!
callbackUrl: String!
securityToken: String!
alertRecurrence: AlertRecurrence!
conditions: PriceEventWebhookConditionInput!
retrySettings: RetrySettingsInput
bucketKey: BucketKeyInput
publishingType: PublishingType
deduplicate: Boolean
}
input CreatePriceWebhooksInput {
webhooks: [CreatePriceWebhookArgs!]!
}
input OneOfNumberConditionInput {
oneOf: [Int!]!
}
input TokenPairEventTypeConditionInput {
oneOf: [TokenPairEventType!]!
}
input TokenPairEventWebhookConditionInput {
networkId: OneOfNumberConditionInput
maker: StringEqualsConditionInput
pairAddress: StringEqualsConditionInput
exchangeAddress: StringEqualsConditionInput
tokenAddress: StringEqualsConditionInput
swapValue: ComparisonOperatorInput
eventType: TokenPairEventTypeConditionInput
}
input CreateTokenPairEventWebhookArgs {
name: String!
callbackUrl: String!
securityToken: String!
alertRecurrence: AlertRecurrence!
conditions: TokenPairEventWebhookConditionInput!
retrySettings: RetrySettingsInput
bucketKey: BucketKeyInput
publishingType: PublishingType
deduplicate: Boolean
}
input CreateTokenPairEventWebhooksInput {
webhooks: [CreateTokenPairEventWebhookArgs!]!
}
input StringContainsConditionInput {
contains: [String!]
notContains: [String!]
}
input RawTransactionWebhookConditionInput {
networkId: OneOfNumberConditionInput
to: StringEqualsConditionInput
from: StringEqualsConditionInput
toOrFrom: StringEqualsConditionInput
input: StringContainsConditionInput
ignoreTokenPairEvents: Boolean
}
input CreateRawTransactionWebhookArgs {
name: String!
callbackUrl: String!
securityToken: String!
alertRecurrence: AlertRecurrence!
conditions: RawTransactionWebhookConditionInput!
retrySettings: RetrySettingsInput
bucketKey: BucketKeyInput
publishingType: PublishingType
deduplicate: Boolean
}
input CreateRawTransactionWebhooksInput {
webhooks: [CreateRawTransactionWebhookArgs!]!
}
input MarketCapEventWebhookConditionInput {
tokenAddress: StringEqualsConditionInput!
networkId: IntEqualsConditionInput!
fdvMarketCapUsd: ComparisonOperatorInput
circulatingMarketCapUsd: ComparisonOperatorInput
pairAddress: StringEqualsConditionInput
volumeUsd: ComparisonOperatorInput
liquidityUsd: ComparisonOperatorInput
}
input CreateMarketCapWebhookArgs {
name: String!
callbackUrl: String!
securityToken: String!
alertRecurrence: AlertRecurrence!
conditions: MarketCapEventWebhookConditionInput!
retrySettings: RetrySettingsInput
bucketKey: BucketKeyInput
publishingType: PublishingType
deduplicate: Boolean
}
input CreateMarketCapWebhooksInput {
webhooks: [CreateMarketCapWebhookArgs!]!
}
input TokenPriceEventWebhookConditionInput {
address: StringEqualsConditionInput!
networkId: IntEqualsConditionInput!
priceUsd: ComparisonOperatorInput!
}
input CreateTokenPriceEventWebhookArgs {
name: String!
callbackUrl: String!
securityToken: String!
alertRecurrence: AlertRecurrence!
conditions: TokenPriceEventWebhookConditionInput!
retrySettings: RetrySettingsInput
bucketKey: BucketKeyInput
publishingType: PublishingType
deduplicate: Boolean
}
input CreateTokenPriceEventWebhooksInput {
webhooks: [CreateTokenPriceEventWebhookArgs!]!
}
input OneOfTokenTransferDirectionConditionInput {
oneOf: [TokenTransferDirection!]!
}
input TokenTransferEventWebhookConditionInput {
tokenAddress: StringEqualsConditionInput
networkId: OneOfNumberConditionInput
address: StringEqualsConditionInput
direction: OneOfTokenTransferDirectionConditionInput
}
input CreateTokenTransferEventWebhookArgs {
name: String!
callbackUrl: String!
securityToken: String!
alertRecurrence: AlertRecurrence!
conditions: TokenTransferEventWebhookConditionInput!
retrySettings: RetrySettingsInput
bucketKey: BucketKeyInput
publishingType: PublishingType
deduplicate: Boolean
}
input CreateTokenTransferEventWebhooksInput {
webhooks: [CreateTokenTransferEventWebhookArgs!]!
}
input PredictionTradeEventTypeConditionInput {
oneOf: [PredictionTradeEventType!]!
}
input PredictionTradeWebhookConditionInput {
traderId: StringEqualsConditionInput
marketId: StringEqualsConditionInput
eventId: StringEqualsConditionInput
eventType: PredictionTradeEventTypeConditionInput
tradeValueUsd: ComparisonOperatorInput
amountToken: ComparisonOperatorInput
}
input CreatePredictionTradeWebhookArgs {
name: String!
callbackUrl: String!
securityToken: String!
alertRecurrence: AlertRecurrence!
conditions: PredictionTradeWebhookConditionInput!
retrySettings: RetrySettingsInput
bucketKey: BucketKeyInput
}
input CreatePredictionTradeWebhooksInput {
webhooks: [CreatePredictionTradeWebhookArgs!]!
}
input WindowedPredictionMarketMetricsEventMarketConditionInput {
volumeUsd: ComparisonOperatorInput
trades: ComparisonOperatorInput
volumeChange: ComparisonOperatorInput
tradesChange: ComparisonOperatorInput
}
input PredictionMarketMetricsEventMarketConditionInput {
min5: WindowedPredictionMarketMetricsEventMarketConditionInput
hour1: WindowedPredictionMarketMetricsEventMarketConditionInput
hour4: WindowedPredictionMarketMetricsEventMarketConditionInput
hour12: WindowedPredictionMarketMetricsEventMarketConditionInput
day1: WindowedPredictionMarketMetricsEventMarketConditionInput
week1: WindowedPredictionMarketMetricsEventMarketConditionInput
}
input WindowedPredictionMarketMetricsEventOutcomeConditionInput {
price: ComparisonOperatorInput
priceChange: ComparisonOperatorInput
volumeUsd: ComparisonOperatorInput
volumeChange: ComparisonOperatorInput
trades: ComparisonOperatorInput
tradesChange: ComparisonOperatorInput
}
input PredictionMarketMetricsEventOutcomeConditionInput {
min5: WindowedPredictionMarketMetricsEventOutcomeConditionInput
hour1: WindowedPredictionMarketMetricsEventOutcomeConditionInput
hour4: WindowedPredictionMarketMetricsEventOutcomeConditionInput
hour12: WindowedPredictionMarketMetricsEventOutcomeConditionInput
day1: WindowedPredictionMarketMetricsEventOutcomeConditionInput
week1: WindowedPredictionMarketMetricsEventOutcomeConditionInput
}
input PredictionMarketMetricsEventWebhookConditionInput {
marketId: StringEqualsConditionInput!
market: PredictionMarketMetricsEventMarketConditionInput
outcome0: PredictionMarketMetricsEventOutcomeConditionInput
outcome1: PredictionMarketMetricsEventOutcomeConditionInput
anyOutcome: PredictionMarketMetricsEventOutcomeConditionInput
}
input CreatePredictionMarketMetricsEventWebhookArgs {
name: String!
callbackUrl: String!
securityToken: String!
alertRecurrence: AlertRecurrence!
conditions: PredictionMarketMetricsEventWebhookConditionInput!
retrySettings: RetrySettingsInput
bucketKey: BucketKeyInput
publishingType: PublishingType
deduplicate: Boolean
}
input CreatePredictionMarketMetricsEventWebhooksInput {
webhooks: [CreatePredictionMarketMetricsEventWebhookArgs!]!
}
input CreateWebhooksInput {
tokenPairEventWebhooksInput: CreateTokenPairEventWebhooksInput
rawTransactionWebhooksInput: CreateRawTransactionWebhooksInput
marketCapWebhooksInput: CreateMarketCapWebhooksInput
tokenPriceEventWebhooksInput: CreateTokenPriceEventWebhooksInput
tokenTransferEventWebhooksInput: CreateTokenTransferEventWebhooksInput
predictionTradeWebhooksInput: CreatePredictionTradeWebhooksInput
predictionMarketMetricsEventWebhooksInput: CreatePredictionMarketMetricsEventWebhooksInput
}
```
## Overview
The `createWebhooks` mutation creates one or more webhooks that push real-time events from Codex to an HTTP endpoint you control. For filter conditions, payload shapes, and message verification details for each webhook type, see the [Webhooks concept page](/concepts/webhooks).
## Available webhook types
Codex supports the following webhook types. Each is documented in detail on the [Webhooks concept page](/concepts/webhooks):
* [Token Pair Event](/concepts/webhooks#token_pair_event): swaps, mints, burns, and other pair-level events. Most common.
* [Token Price Event](/concepts/webhooks#token_price_event): token price crosses a threshold.
* [Token Transfer Event](/concepts/webhooks#token_transfer_event): tokens moved to or from a wallet.
* [Market Cap Event](/concepts/webhooks#market_cap_event): fully diluted or circulating market cap crosses a threshold.
* [Prediction Trade Event](/concepts/webhooks#prediction_trade_event): Polymarket or Kalshi prediction trade.
* [Prediction Market Metrics Event](/concepts/webhooks#prediction_market_metrics_event): rolling volume, price, or trade-count stats over windows from 5m to 1w cross a threshold on a Polymarket or Kalshi market, at the market or per-outcome level.
## Quick example
Test this query in the Explorer →
A minimal mutation that creates a `TOKEN_PAIR_EVENT` webhook firing on any swap over \$10,000 on a specific pair:
```graphql theme={null} theme={null}
mutation {
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
}
}
}
```
## Usage Guidelines
* Your endpoint must return a 2xx response within 3 seconds, or the message will be retried
* Use `bucketKey` to group related webhooks. The individual `bucketId` and `bucketSortKey` fields are deprecated
* Use `publishingType: BATCH` for high-volume webhooks like `TOKEN_PAIR_EVENT` to reduce HTTP requests to your endpoint
* For `MARKET_CAP_EVENT` webhooks, combine market cap thresholds with `volumeUsd` and `liquidityUsd` filters (using `gt`, `gte`, `lt`, `lte`, `eq` operators) to ensure quality results
* Verify every webhook message with the `X-Webhook-Timestamp` and `X-Webhook-Signature` headers. The legacy `hash` field is deprecated; see [Hash verification](/concepts/webhooks#hash_verification) for migration details
* Use the [Codex Explorer](https://explorer.codex.io) to build webhook mutations visually before wiring up production
## Troubleshooting Tips
Check that your endpoint returns a 2xx response within 3 seconds. If your endpoint is slow, you may be getting duplicate messages from retries. You can inspect webhook status in the [Codex Dashboard](https://dashboard.codex.io).
Double-check that the `networkId` on your condition matches the network the token or pair lives on. See [supported networks](/networks) for the full list of network IDs.
Use the `deduplicationId` field on each message to deduplicate on your side. Retries reuse the same `deduplicationId`.
Use the [Codex Explorer](https://explorer.codex.io) to build the mutation visually and send a test message to your endpoint.
If your webhook receiver sits behind a firewall, IP allowlist, or other network-level filtering, deliveries can be dropped before they reach your application. Codex sends webhooks from a fixed set of source IPs — see [Source IP addresses](https://docs.codex.io/concepts/webhooks#source-ip-addresses) on the Webhooks concept page for the current list to allowlist.