Create Webhook

Create a new webhook subscription to receive realtime onchain data.

POST /beta/evm/subscriptions/webhooks

Create a webhook

cURL

curl --request POST \
  --url https://api.sim.dune.com/beta/evm/subscriptions/webhooks \
  --header 'Content-Type: application/json' \
  --header 'X-Sim-Api-Key: <x-sim-api-key>' \
  --data '
{
  "name": "USDC Balance Monitor",
  "url": "https://example.com/webhooks/usdc-balances",
  "type": "balances",
  "addresses": [
    "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
  ],
  "chain_ids": [
    1,
    8453
  ],
  "asset_type": "erc20",
  "token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
}
'

200

{
  "id": "019a81c2-d84b-7141-85e8-86b072a59142",
  "team_id": "01K7RVMRT0BXQ9DRC8BK87MK39",
  "name": "Balance Changes Tracker",
  "type": "balances",
  "url": "https://example.com/webhooks/balances",
  "active": true,
  "created_at": "2025-11-14T09:47:01.580104Z",
  "updated_at": "2025-11-14T09:47:01.580104Z",
  "chain_ids": [
    1,
    8453,
    84532
  ]
}

Creates a new webhook subscription. When creating a webhook, you must specify:

• name: A descriptive name for your webhook
• url: The endpoint where webhook payloads will be sent
• type: The type of events to subscribe to (transactions, activities, or balances)
• addresses: An array of wallet addresses to monitor

Optional Filters

You can narrow down the events you receive by adding optional filters:

• chain_ids: Monitor only specific chains (e.g., [1, 8453] for Ethereum and Base)
• transaction_type: For transaction webhooks, filter by sender or receiver
• counterparty: Filter transactions by counterparty address
• activity_type: For activity webhooks, filter by specific types (send, receive, swap, etc.)
• asset_type: Filter by asset type (native, erc20, erc721, erc1155)
• token_address: Monitor only a specific token contract

Start with broad filters and narrow them down based on your app’s needs. This helps reduce unnecessary webhook deliveries.

Example Use Cases

Monitor USDC Balance Changes

{
  "name": "USDC Balance Monitor",
  "url": "https://example.com/webhooks/usdc",
  "type": "balances",
  "addresses": ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"],
  "chain_ids": [1, 8453],
  "asset_type": "erc20",
  "token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
}

Track All Incoming Transactions

{
  "name": "Incoming Transactions",
  "url": "https://example.com/webhooks/txns",
  "type": "transactions",
  "addresses": ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"],
  "transaction_type": "receiver"
}

Monitor Swap Activities

{
  "name": "Swap Monitor",
  "url": "https://example.com/webhooks/swaps",
  "type": "activities",
  "addresses": ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"],
  "activity_type": "swap"
}

Headers

X-Sim-Api-Key · string · required

Used for authenticating requests. Provide an API key with a purpose of Sim API. See Authentication.

Body

application/json

name · string · required

A descriptive name for the webhook.

url · string<uri> · required

The URL where webhook payloads will be sent.

type · enum<string> · required

The type of onchain event to subscribe to.

Available options: transactions, activities, balances

addresses · string[] · required

List of addresses to monitor.

EVM address.

chain_ids · integer<int64>[] | null

Filter events to specific chain IDs. If omitted, all supported chains are included.

transaction_type · enum<string> | null

ONLY for 'transactions' type webhooks. Filter by sender or receiver. Cannot be used with other webhook types.

Available options: sender, receiver

counterparty · string | null

ONLY for 'transactions' type webhooks. Filter transactions by counterparty address.

activity_type · enum<string> | null

ONLY for 'activities' type webhooks. Filter by specific activity type. Cannot be used with other webhook types.

Available options: approve, mint, burn, receive, send, swap, call

asset_type · enum<string> | null

Filter by asset type.

Available options: native, erc20, erc721, erc1155

token_address · string | null

Filter events to a specific token address.

Response

200

application/json

Webhook created successfully.

id · string<uuid>

The unique identifier for the webhook.

team_id · string

The team ID that owns this webhook.

name · string

A descriptive name for the webhook.

type · enum<string>

The type of onchain event to subscribe to.

Available options: transactions, activities, balances

url · string<uri>

The URL where webhook payloads will be sent.

active · boolean

Whether the webhook is currently active.

created_at · string<date-time>

When the webhook was created.

updated_at · string<date-time>

When the webhook was last updated.

chain_ids · integer<int64>[] | null

Filter events to specific chain IDs. If null, all supported chains are included.

transaction_type · enum<string> | null

For transaction webhooks, filter by sender or receiver.

Available options: sender, receiver

counterparty · string | null

Filter transactions by counterparty address.

Example:

"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

activity_type · enum<string> | null

For activity webhooks, filter by specific activity type.

Available options: approve, mint, burn, receive, send, swap, call

asset_type · enum<string> | null

Filter by asset type.

Available options: native, erc20, erc721, erc1155

token_address · string | null

Filter events to a specific token address.

Example:

"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"