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

# Create webhook subscription

> Subscribes a webhook URL to incoming transfers for one (chain, address) pair.



## OpenAPI

````yaml /openapi.json post /api/notifications/subscriptions
openapi: 3.1.0
info:
  title: WalletSuite REST API
  description: >-
    Multi-chain wallet operations, balances, prices, and transaction lifecycle
    as a REST API.
  contact:
    name: WalletSuite
    url: https://walletsuite.io
  version: prod
servers:
  - url: https://api.walletsuite.io
    description: WalletSuite API
security:
  - ApiKeyAuth: []
tags:
  - name: Transactions
    description: >-
      Get transaction history by address, check live transaction status, and
      send signed transactions.
  - name: Fees
    description: Fee estimation endpoints
  - name: Balances
    description: Fetch balances on any supported chain (Ethereum, Tron).
  - name: Assets
    description: >-
      List supported blockchain assets from the database loaded at startup from
      bundled resources
  - name: Asset Status
    description: Asset enablement and restrictions.
  - name: Prices
    description: Fiat prices for symbols and contract addresses
  - name: Swaps
    description: Swap quote, route, and transaction building.
  - name: Approvals
    description: Allowance, approval tx data, and approval status.
  - name: NFTs
    description: NFT collections, tokens, owners, and transfer building.
  - name: Staking
    description: Native staking APR, validators, positions, and transaction building.
  - name: Name Service
    description: Name resolution and reverse resolution.
  - name: Chains
    description: Chain registry and chain capabilities.
  - name: Chain Specific
    description: Chain specific endpoints consumable by SDK.
  - name: Blocks
    description: View most recently indexed block information.
  - name: Info
    description: General information and summary counts.
paths:
  /api/notifications/subscriptions:
    post:
      tags:
        - Webhooks
      summary: Create webhook subscription
      description: >-
        Subscribes a webhook URL to incoming transfers for one (chain, address)
        pair.
      operationId: createSubscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionRequest'
      responses:
        '202':
          description: Accepted - registration in progress
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ApiResponseSubscriptionView'
        '400':
          description: Invalid request (BAD_REQUEST, WEBHOOK_URL_NOT_ALLOWED)
        '401':
          description: Missing or invalid API key
        '403':
          description: Plan does not include NOTIFICATIONS_SUBSCRIBE
        '409':
          description: SUBSCRIPTION_EXISTS or SUBSCRIPTION_LIMIT_REACHED
components:
  schemas:
    CreateSubscriptionRequest:
      type: object
      required:
        - chain
        - address
        - eventKinds
        - webhookUrl
      properties:
        chain:
          type: string
          enum:
            - ethereum
            - tron
          description: Chain to watch.
        address:
          type: string
          maxLength: 128
          description: Address to watch for incoming transfers.
        eventKinds:
          type: array
          maxItems: 8
          items:
            type: string
            enum:
              - INCOMING_NATIVE
              - INCOMING_FUNGIBLE
          description: 'Asset-scope filters: which incoming transfer kinds to deliver.'
        webhookUrl:
          type: string
          maxLength: 2048
          description: >-
            HTTPS endpoint (port 443, publicly resolvable) that receives
            deliveries.
    ApiResponseSubscriptionView:
      type: object
      properties:
        ok:
          type: boolean
        code:
          type: string
        message:
          type: string
        data:
          $ref: '#/components/schemas/SubscriptionView'
    SubscriptionView:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the subscription.
        chain:
          type: string
          description: Watched chain id, e.g. ethereum or tron (open enum).
        address:
          type: string
          description: >-
            The watched on-chain address. Events fire for incoming transfers to
            this address.
        eventKinds:
          type: array
          items:
            type: string
          description: >-
            Asset-scope filters set at create time: INCOMING_NATIVE (native-coin
            transfers) and/or INCOMING_FUNGIBLE (token transfers).
        webhookUrl:
          type: string
          description: HTTPS delivery endpoint. Signed deliveries are POSTed here.
        status:
          type: string
          description: >-
            pending | active | failed | paused | deleted (open enum - new values
            may appear).
        createdAt:
          type: string
          format: date-time
          description: Creation time, ISO-8601 UTC.
        failureCount:
          type: integer
          description: >-
            Consecutive failed deliveries; resets on success, climbs toward the
            auto-pause threshold.
        lastSuccessAt:
          type:
            - string
            - 'null'
          format: date-time
          description: When the last delivery succeeded (UTC), or null if none yet.
        pausedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: When auto-paused (UTC); null unless status is 'paused'.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: API key provided by WalletSuite team
      name: x-api-key
      in: header

````