Custom Webhook Variables

Understand how Custom Webhook variables work and how to use them

With GraphQL, Alchemy's Custom Webhook is able to leverage the power of variables to dynamically insert values into a webhook query. In particular, users are able to filter data based on both addresses and log topics via Custom Webhook variables!

📘

NOTE:

To use a variable, you must first create it using one of the Custom Webhook API methods that allow you to create, read, update, and destroy Custom Webhook variables!

Variable Types

Custom Webhook variables can either be a set of addresses or bytes32 objects. This allows developers to either define variables for transaction level filters or logs!

Example Address Typed Variables

Variable Name:addressVariable

Variable Value: {0x5c43B1eD97e52d009611D89b74fA829FE4ac56b1, 0x95222290DD7278Aa3Ddd389Cc1E1d165CC4BAfe5, 0x388C818CA8B9251b393131C08a736A67ccB19297 }

Address typed variables can be used in either [external transaction filters](External Transaction Filters) and/or internal transaction filters.

Example Log Topic Typed Variables

Variable Name:logTopicVariable

Variable Value: {0xe1fffcc4923d04b559f4d29a8bfc6cda04eb5b0d3c460751c2402c5c5cc9109c, 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef, 0xd78ad95fa46c994b6551d0da85fc275fe613ce37657fb8d5e3d130840159d822 }

Log Topic typed variables can be used in only event log filters!

📘

NOTE:

Log Topic typed variables can represent an array of topic0, topic1, or topic2 elements.

  • topic0 is the hash of the event signature. The event signature is the canonical representation of an event's name and its argument types. If the event signature is Transfer(address, address, uint256), then thetopic0 will be the Keccak-256 hash of this string. This allows listeners (e.g., dapps, wallets) to identify and filter events of a specific type
  • topic1/ topic2 are indexed parameters and are used to store the indexed parameters of the event. These indexed parameters are stored in the topics, allowing for more efficient filtering and

How to Use Variables in Custom Webhooks

📘

NOTE:

Variable Declaration:

At the beginning of each GraphQL query where you want to use a variable, you must declare the variable!

  • Here's an example variable declaration where you want to use just an address typed variable:

query ($addressVariable: [Address!])

  • Here's an example variable declaration where you want to use both an address typed variable and a log topic typed variable:

query ($addressVariable: [Address!], $logTopicVariable:[Bytes32!]!)

Examples Using A Variable:

Single Variable Custom Webhooks

In this example, we use a variable addressVar which is applied to an external transaction filter, specifically within the from address parameter.

query ($addressVar: [Address!]) {
  block {
    hash
    number
    transactions(filter: {addresses: [{from: $addressVar }]}) {
      hash
      from {
        address
      }
      to {
        address
      }
      value
      gas
      status
      logs {
        data
        topics
      }
    }
  }
}

Multi-Variable Custom Webhooks

In this example, we use 2 variables addressVar AND logTopic0 with the former being used in an external transaction filter and the former being applied to the event log filter.

query ($addressVar: [Address!], $logTopic0:[Bytes32!]!) {
  block {
    hash
    number
    transactions(filter: {addresses: [{to: $addressVar }]}) {
      hash
      from {
        address
      }
      to {
        address
      }
      value
      gas
      status
      logs {
        data
        topics
      }
    }
    logs(filter: { addresses: [], topics: [$logTopic0, [],[]] }) {
    topics
    transaction{
      hash
      from {
        address
      }
      to {
        address
      }
      value
      gas
      status
    }
  }
  }
}

FAQ

How many elements can I use within a Custom Webhook variable?

Each Custom Webhook variable can contain up to 5 million elements by default! If you would like to raise this limit, please reach out to [email protected] and we can work with you to increase your variable size!