> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sim.dune.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Webhook

> Create a new webhook subscription to receive realtime onchain data.

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

<Tip>
  Start with broad filters and narrow them down based on your app's needs. This helps reduce unnecessary webhook deliveries.
</Tip>

## Example Use Cases

### Monitor USDC Balance Changes

```json theme={null}
{
  "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

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

### Monitor Swap Activities

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


## OpenAPI

````yaml /openapi.json POST /beta/evm/subscriptions/webhooks
openapi: 3.0.3
info:
  title: Sim API
  description: >-
    The Sim API by Dune provides real-time blockchain data across EVM and SVM
    chains. Access token balances, transaction history, on-chain activity, DeFi
    positions, NFT collectibles, token information, and webhook subscriptions
    through a unified REST API.
  version: 1.0.0
  license:
    name: ''
  contact:
    name: Dune Support
    url: https://docs.sim.dune.com
    email: support@dune.com
servers:
  - url: https://api.sim.dune.com
security:
  - ApiKeyAuth: []
tags:
  - name: evm
    description: EVM-compatible blockchain endpoints.
  - name: svm
    description: Solana/SVM blockchain endpoints.
  - name: activity
    description: On-chain activity feed.
  - name: balances
    description: Token balances (EVM and SVM).
  - name: transactions
    description: Transaction history (EVM and SVM).
  - name: collectibles
    description: NFT and ERC721/ERC1155 holdings.
  - name: defi
    description: DeFi protocol positions.
  - name: supported-chains
    description: Supported blockchain networks.
  - name: token-info
    description: Token metadata and pricing.
  - name: token-holders
    description: Token holder distribution.
  - name: subscriptions
    description: >-
      Webhook subscription management for real-time on-chain event
      notifications.
paths:
  /beta/evm/subscriptions/webhooks:
    post:
      tags:
        - evm
        - subscriptions
      summary: Create a webhook
      description: Creates a new webhook subscription.
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhook'
            example:
              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'
      responses:
        '200':
          description: Webhook created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
              example:
                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
        '422':
          description: Validation error for request body.
          content:
            text/plain:
              schema:
                type: string
                example: >-
                  Failed to deserialize the JSON body into the target type:
                  missing field `name` at line 1 column 2
        '429':
          description: Rate Limit Exceeded - Too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayErrorResponse'
              examples:
                rateLimitExceeded:
                  value:
                    error: >-
                      Too many requests. Please contact sales@dune.com to
                      increase your limit.
components:
  schemas:
    CreateWebhook:
      type: object
      required:
        - name
        - url
        - type
        - addresses
      properties:
        name:
          type: string
          description: A descriptive name for the webhook.
        url:
          type: string
          format: uri
          description: The URL where webhook payloads will be sent.
        type:
          $ref: '#/components/schemas/WebhookType'
        addresses:
          type: array
          items:
            type: string
            description: EVM address.
          description: List of addresses to monitor.
        chain_ids:
          type: array
          items:
            type: integer
            format: int64
          nullable: true
          description: >-
            Filter events to specific chain IDs. If omitted, all supported
            chains are included.
        transaction_type:
          allOf:
            - $ref: '#/components/schemas/TransactionType'
          nullable: true
          description: >-
            ONLY for 'transactions' type webhooks. Filter by sender or receiver.
            Cannot be used with other webhook types.
          type: string
        counterparty:
          type: string
          nullable: true
          description: >-
            ONLY for 'transactions' type webhooks. Filter transactions by
            counterparty address.
        activity_type:
          allOf:
            - $ref: '#/components/schemas/ActivityType'
          nullable: true
          description: >-
            ONLY for 'activities' type webhooks. Filter by specific activity
            type. Cannot be used with other webhook types.
          type: string
        asset_type:
          allOf:
            - $ref: '#/components/schemas/AssetType'
          nullable: true
          description: Filter by asset type.
          type: string
        token_address:
          type: string
          nullable: true
          description: Filter events to a specific token address.
    Webhook:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier for the webhook.
        team_id:
          type: string
          description: The team ID that owns this webhook.
        name:
          type: string
          description: A descriptive name for the webhook.
        type:
          $ref: '#/components/schemas/WebhookType'
        url:
          type: string
          format: uri
          description: The URL where webhook payloads will be sent.
        active:
          type: boolean
          description: Whether the webhook is currently active.
        created_at:
          type: string
          format: date-time
          description: When the webhook was created.
        updated_at:
          type: string
          format: date-time
          description: When the webhook was last updated.
        chain_ids:
          type: array
          items:
            type: integer
            format: int64
          nullable: true
          description: >-
            Filter events to specific chain IDs. If null, all supported chains
            are included.
        transaction_type:
          allOf:
            - $ref: '#/components/schemas/TransactionType'
          nullable: true
          description: For transaction webhooks, filter by sender or receiver.
          type: string
        counterparty:
          type: string
          nullable: true
          description: Filter transactions by counterparty address.
          example: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
        activity_type:
          allOf:
            - $ref: '#/components/schemas/ActivityType'
          nullable: true
          description: For activity webhooks, filter by specific activity type.
          type: string
        asset_type:
          allOf:
            - $ref: '#/components/schemas/AssetType'
          nullable: true
          description: Filter by asset type.
          type: string
        token_address:
          type: string
          nullable: true
          description: Filter events to a specific token address.
          example: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
    GatewayErrorResponse:
      type: object
      description: >-
        Error response from the API gateway. Returned for authentication,
        permissions, rate-limiting, and quota errors.
      properties:
        error:
          type: string
          description: Error message.
      required:
        - error
    WebhookType:
      type: string
      enum:
        - transactions
        - activities
        - balances
      description: The type of onchain event to subscribe to.
    TransactionType:
      type: string
      enum:
        - sender
        - receiver
      description: >-
        ONLY for 'transactions' type webhooks. Filter by whether the subscribed
        address is the sender or receiver. Cannot be used with 'balances' or
        'activities' webhook types.
    ActivityType:
      type: string
      enum:
        - approve
        - mint
        - burn
        - receive
        - send
        - swap
        - call
      description: >-
        ONLY for 'activities' type webhooks. Filter by specific activity types.
        Cannot be used with 'balances' or 'transactions' webhook types.
    AssetType:
      type: string
      enum:
        - native
        - erc20
        - erc721
        - erc1155
      description: Filter by asset type.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Sim-Api-Key
      description: >-
        API key for authentication. Obtain your key from the Dune dashboard at
        sim.dune.com.

````