Custom Webhooks FAQ

What chains does Alchemy host Custom Webhooks for?

Custom Webhooks are live for Alchemy's entire EVM network suite. This includes main-net and testnets across Ethereum, Polygon, Arbitrum, and Optimism.

Why do I receive a webhook for every new block?

Don't be alarmed if you're seeing blank data like the following!

{
  "webhookId": "wh_yg0kkvlsnksbzvwz",
  "id": "whevt_3iho0jjd9zsmfgkk",
  "createdAt": "2023-02-02T23:11:24.585Z",
  "type": "GRAPHQL",
  "event": {
    "data": {
      "block": {
        "logs": []
      }
    },
    "sequenceNumber": "10000000000579857000"
  }
}

We send you notifications every time we run your GraphQL queries regardless of whether the filter results are null. This holds us accountable and serves as a receipt that we ran the query on each new canonical block!

How do I use GraphQL to construct a query?

If you're new to GraphQL, the in-browser editor on the [Alchemy Notify Dashboard (https://dashboard.alchemyapi.io/notify has autocomplete enabled and will magically suggest fields as you start typing. If you get lost, you can always search for available queries in the docs tab on the pop-up to the right of the webpage!

Can I add more expressive GraphQL filters?

100% We're hard at work creating new expressions to allow developers to make more complex queries. Keep your eyes peeled for updates and feel free to reach out to [email protected] with any suggestions!

Why am I running into errors when creating a webhook?

Our Custom Webhooks product is still in early access and we have lots of users! We're working on ensuring that the webhook creation and sending process is scalable. If you're seeing 500 error codes when creating webhooks, please ensure that you do not have transactions.inputData included as a parameter in your GraphQL query. We are heads-down working on ensuring reliable access across our entire API surface area!

Help! I'm seeing the error "GraphQL webhooks are currently in beta"!

Hey! Awesome to have you try out our Custom Webhook solution. Please fill out this form and we'll be in touch!

Are there any constraints to the GraphQL interface in Custom Webhooks?

While logs and transactions can be self-referential entities, we only allow for a single-layer nested data structure to bound GraphQL queries. This helps us to to maintain a tidy API surface area.

How do I use the log filter?

• Currently, our log/event filter leverages the same semantics as a traditional topic filter for an eth_getLogs RPC call. If you're not familiar with how topic filters work for eth_getLogs, here's an article to get you up to speed.
• Feel free to peek at our example GraphQL repository as well to get inspiration for the different queries you can make.

How many Custom Webhooks can I create?

For our early access program, we currently have a limit of 16 Custom Webhook endpoints. Feel free to reach out to [email protected] if you would like a higher limit!

How much do Custom Webhooks cost?

Custom Webhooks fall under the Alchemy Notify suite and are priced based on bandwidth: the amount of data delivered as part of the subscription. Each byte of data delivered costs 0.04 CUs. Since you only pay for what you use, feel free to tune each GraphQL to only deliver the information you want!

Once we move past our early access period, we will also include a fixed CU cost for hosting each GraphQL query on Alchemy.

How are reorgs handled?

Custom Webhooks is built on top of Alchemy's Supernode product which powers our RPC service. This ensures that we have a consistent and accurate view of the blockchain. However, it is still possible for re-orgs to take place on the blockchain. If a chain re-org occurs, Alchemy will re-run your GraphQL filters on the latest canonical block and send you a new webhook notification. To de-dup and handle re-orgs client side, Custom Webhook response fields include the property sequenceNumber. sequenceNumber is an incremented integer associated with each webhook notification and can be used by developers to understand if a "new, more correct" block of data has taken place to ensure that developers are always in parity with the current blockchain state.

What does the capacity limit error mean?

The capacity limit error means you've exceeded your total monthly compute units. To upgrade your capacity limits go to your Alchemy dashboard. Below is an example capacity limit error.

{
  "webhookId": "wh_127lzhz0dfwwimwe",
  "id": "whevt_55i2al4sc2ivp1m8",
  "createdAt": "2022-12-05T23:43:16.379Z",
  "type": "GRAPHQL",
  "event": {
    "error": "Monthly capacity limit exceeded. Visit https://dashboard.alchemy.com/settings/billing to upgrade your scaling policy for continued service."
  }
}

What is the x-alchemy-signature?

The x-alchemy-signature is an Alchemy authentication token used to verify the source of your webhook requests and responses. The x-alchemy-signature ensures you’re getting responses from Alchemy and no other malicious source.

Where do I find my Alchemy auth token?

Find your Alchemy auth token in the upper-right corner of your Notify dashboard by clicking the AUTH TOKEN button.