asyncapi: 2.6.0
info:
  title: Uniblock Webhook Events
  description: >-
    Uniblock webhooks enable real-time notifications for blockchain events
    without the need to poll endpoints. By configuring webhooks through the
    Uniblock dashboard or API, developers can receive HTTP callbacks whenever
    specific on-chain activities occur, such as address activity, token
    transfers, NFT transfers, and mined transactions. Webhook payloads include
    detailed event data and are signed for authentication.
  version: '1.0'
  contact:
    name: Uniblock Support
    url: https://docs.uniblock.dev
  externalDocs:
    description: Uniblock Webhook Documentation
    url: https://docs.uniblock.dev/docs/event-trigger-types
servers:
  webhookServer:
    url: '{webhookUrl}'
    protocol: https
    description: >-
      Your application's webhook endpoint URL configured in the Uniblock
      dashboard. Uniblock sends HTTP POST requests to this URL when matching
      blockchain events are detected.
    variables:
      webhookUrl:
        description: >-
          The HTTPS URL of your webhook endpoint that will receive event
          notifications.
    security:
      - webhookSignature: []
channels:
  /webhook/address-activity:
    description: >-
      Notifications triggered when a tracked address sends or receives
      transactions, including native token transfers and token activity.
      Provides real-time insights into portfolio changes and wallet movements.
    publish:
      operationId: onAddressActivity
      summary: Address activity event
      description: >-
        Triggered when a monitored blockchain address has any inbound or
        outbound transaction activity, including native token sends and
        receives.
      message:
        $ref: '#/components/messages/AddressActivityEvent'
  /webhook/token-transfer:
    description: >-
      Notifications triggered when fungible token transfers occur involving
      tracked addresses or contracts, including ERC-20 transfers, approvals,
      and swap events.
    publish:
      operationId: onTokenTransfer
      summary: Token transfer event
      description: >-
        Triggered when a fungible token transfer occurs that matches the
        configured filter criteria, such as specific sender or receiver
        addresses or token contract addresses.
      message:
        $ref: '#/components/messages/TokenTransferEvent'
  /webhook/nft-transfer:
    description: >-
      Notifications triggered when NFT transfers occur involving tracked
      addresses or collections, including mints, sales, and transfers.
    publish:
      operationId: onNftTransfer
      summary: NFT transfer event
      description: >-
        Triggered when an NFT transfer event occurs that matches the
        configured filter criteria, including ERC-721 and ERC-1155 transfers.
      message:
        $ref: '#/components/messages/NftTransferEvent'
  /webhook/mined-transaction:
    description: >-
      Notifications triggered when a specific pending transaction is
      confirmed and included in a mined block.
    publish:
      operationId: onMinedTransaction
      summary: Mined transaction event
      description: >-
        Triggered when a transaction that was being monitored has been
        successfully mined and confirmed on the blockchain.
      message:
        $ref: '#/components/messages/MinedTransactionEvent'
components:
  securitySchemes:
    webhookSignature:
      type: httpApiKey
      name: x-uniblock-signature
      in: header
      description: >-
        HMAC signature used to verify that webhook payloads originate from
        Uniblock. Computed using the webhook secret key configured in the
        Uniblock dashboard.
  messages:
    AddressActivityEvent:
      name: AddressActivityEvent
      title: Address Activity Event
      summary: >-
        Notification of transaction activity involving a tracked address.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/AddressActivityPayload'
    TokenTransferEvent:
      name: TokenTransferEvent
      title: Token Transfer Event
      summary: >-
        Notification of a fungible token transfer matching configured filters.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/TokenTransferPayload'
    NftTransferEvent:
      name: NftTransferEvent
      title: NFT Transfer Event
      summary: >-
        Notification of an NFT transfer matching configured filters.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/NftTransferPayload'
    MinedTransactionEvent:
      name: MinedTransactionEvent
      title: Mined Transaction Event
      summary: >-
        Notification that a monitored transaction has been mined and confirmed.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/MinedTransactionPayload'
  schemas:
    WebhookMetadata:
      type: object
      description: >-
        Common metadata included in all webhook event payloads.
      properties:
        webhookId:
          type: string
          description: >-
            The unique identifier of the webhook subscription that triggered
            this notification.
        eventType:
          type: string
          description: >-
            The type of event that triggered the webhook.
          enum:
            - ADDRESS_ACTIVITY
            - TOKEN_TRANSFER
            - NFT_TRANSFER
            - MINED_TRANSACTION
        chain:
          type: string
          description: >-
            The blockchain network on which the event occurred.
        timestamp:
          type: string
          format: date-time
          description: >-
            The timestamp when the event was detected by Uniblock.
    AddressActivityPayload:
      type: object
      description: >-
        Payload delivered when transaction activity is detected for a
        monitored address.
      properties:
        metadata:
          $ref: '#/components/schemas/WebhookMetadata'
        data:
          type: object
          description: >-
            Address activity event data.
          properties:
            address:
              type: string
              description: >-
                The monitored address involved in the activity.
            direction:
              type: string
              description: >-
                Whether the address was the sender or receiver.
              enum:
                - inbound
                - outbound
            transactionHash:
              type: string
              description: >-
                The hash of the transaction.
            from:
              type: string
              description: >-
                The sender address.
            to:
              type: string
              description: >-
                The recipient address.
            value:
              type: string
              description: >-
                The value transferred in the native token's smallest unit.
            blockNumber:
              type: integer
              description: >-
                The block number containing the transaction.
            blockTimestamp:
              type: string
              format: date-time
              description: >-
                The timestamp of the block.
    TokenTransferPayload:
      type: object
      description: >-
        Payload delivered when a token transfer event is detected.
      properties:
        metadata:
          $ref: '#/components/schemas/WebhookMetadata'
        data:
          type: object
          description: >-
            Token transfer event data.
          properties:
            transactionHash:
              type: string
              description: >-
                The hash of the transaction containing the transfer.
            from:
              type: string
              description: >-
                The sender address.
            to:
              type: string
              description: >-
                The recipient address.
            contractAddress:
              type: string
              description: >-
                The smart contract address of the transferred token.
            tokenName:
              type: string
              description: >-
                The name of the transferred token.
            tokenSymbol:
              type: string
              description: >-
                The symbol of the transferred token.
            value:
              type: string
              description: >-
                The amount transferred in the token's smallest unit.
            decimals:
              type: integer
              description: >-
                The number of decimal places for the token.
            blockNumber:
              type: integer
              description: >-
                The block number containing the transfer.
            blockTimestamp:
              type: string
              format: date-time
              description: >-
                The timestamp of the block.
    NftTransferPayload:
      type: object
      description: >-
        Payload delivered when an NFT transfer event is detected.
      properties:
        metadata:
          $ref: '#/components/schemas/WebhookMetadata'
        data:
          type: object
          description: >-
            NFT transfer event data.
          properties:
            transactionHash:
              type: string
              description: >-
                The hash of the transaction containing the transfer.
            from:
              type: string
              description: >-
                The sender address.
            to:
              type: string
              description: >-
                The recipient address.
            contractAddress:
              type: string
              description: >-
                The smart contract address of the NFT collection.
            tokenId:
              type: string
              description: >-
                The token ID of the transferred NFT.
            tokenType:
              type: string
              description: >-
                The token standard type.
              enum:
                - ERC-721
                - ERC-1155
            quantity:
              type: integer
              description: >-
                The number of tokens transferred (relevant for ERC-1155).
            blockNumber:
              type: integer
              description: >-
                The block number containing the transfer.
            blockTimestamp:
              type: string
              format: date-time
              description: >-
                The timestamp of the block.
    MinedTransactionPayload:
      type: object
      description: >-
        Payload delivered when a monitored transaction has been mined.
      properties:
        metadata:
          $ref: '#/components/schemas/WebhookMetadata'
        data:
          type: object
          description: >-
            Mined transaction event data.
          properties:
            transactionHash:
              type: string
              description: >-
                The hash of the mined transaction.
            from:
              type: string
              description: >-
                The sender address.
            to:
              type: string
              description: >-
                The recipient address.
            value:
              type: string
              description: >-
                The value transferred in the native token's smallest unit.
            status:
              type: string
              description: >-
                The execution status of the transaction.
              enum:
                - success
                - failed
            blockNumber:
              type: integer
              description: >-
                The block number in which the transaction was mined.
            blockTimestamp:
              type: string
              format: date-time
              description: >-
                The timestamp of the block.
            gasUsed:
              type: string
              description: >-
                The amount of gas consumed by the transaction.