Webhooks FAQ

General

What chains are supported for webhooks?

We support 80+ chains. Check here for the most updated view of which networks are supported for webhooks (or other Alchemy products).

How many webhooks can I create?

These are the number of webhooks you can create per tier!

How much do webhooks cost?

Webhooks are priced based on bandwidth: the amount of data delivered to your endpoint. The current rate is maintained on this page.

At the current pricing rate, for many use cases, this averages out to about ~40 CUs per event.

Setup and Configuration

What are best practices for constructing a GraphQL query for a Custom Webhook?

We have a number of resources to help you accomplish this! The templates in the webhooks creation flow cover most common use cases, and there are some more examples in we have shared in this public repo.

An alternative solution is to plug this query schema into ChatGPT or another LLM and ask it to write a query (e.g. Take this schema and write me query that triggers for all events on my smart contract 0x…)

How can I filter logs with specific event parameters on Custom Webhooks?

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 those calls, check out this primer on Custom Webhook Filters

Can I add more advanced GraphQL filtering to my webhook queries?

Take a look at this repo of more complex queries! An alternative solution is to plug this query schema into chatGPT and ask it to write a query (e.g. Take this schema and write me query that triggers for all events on my smart contract 0x…)

Are there constraints on GraphQL queries used with 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 many addresses can be tracked by a webhook?

• For Address Activity, we guarantee reliable support for up to 100,000 addresses per webhook.
• For Custom, with custom webhook variables, we support a maximum of 10M addresses per variable currently.
• For NFT Activity, there are no hard set limits.

Behavior and Delivery

Why am I receiving so many webhook events?

• It’s possible you’re tracking highly traffic’d wallet(s) or smart contract(s), resulting in an increase in traffic. Double check your webhooks configuration to be sure!
• For Custom webhooks, it’s possible your query was configured to fire on all blocks, regardless if the filter matches. When creating a custom webhook from the dashboard, ensure the Include Empty Messages checkbox is unchecked. If creating a custom webhook via API, be sure to set the skip_empty_messages parameter to false.
• For NFT Activity webhooks, if filters aren’t set, you will receive activity related to all NFTs on that particular chain!

How are blockchain reorganizations (reorgs) handled?

If a re-org occurs, Alchemy will automatically re-run your webhook filters on the latest canonical (correct) block and send you a new webhook notification. If you see a block number repeated with a new block hash, that means previous events with the same block number were re-org’d out of the canonical chain!

Why am I missing transactions in the response?

Double check that you’re parsing the response payload correctly. Remember, transactions are returned in a list. Transactions that are mined within the same block will be returned within the same activity list.

What if my endpoint goes down?

Webhooks have built-in retry-logic with exponential backoff for non-200 response codes in failures to reach your server. For Free and Pay As You Go tier teams, these will fire with back off up to 10 minutes after. For Enterprise customers, this back off period will extend to 1 hour. We’re looking into expanding this soon, reach out to [email protected] if you’re interested in early access!

What sort of timeouts are set?

Our webhook HTTP requests will timeout if your server doesn’t respond within 5 seconds. Please ensure your service responds to webhook events prior to processing them to ensure you don’t hit this timeout!

How should I respond to webhook HTTP events?

Ensure your webhook listener responses with an HTTP 200 status code to let our service know that you’ve successfully received the HTTP request. Responding with non-200’s will trigger retries, and eventually lead to pausing of your webhooks!

What headers does Alchemy send with webhooks requests?

Example Request Header

$
POST /yourWebhookServer/push HTTP/1.1
>
Content-Type: application/json;
>
X-Alchemy-Signature: your-hashed-signature

Error Handling and Troubleshooting

Why did my webhooks pause?

Your webhooks can be automatically paused if you hit your account’s capacity limit or your webhook listener consistently responds with non-2xx HTTP status codes. Go to your webhook dashboard and hover your cursor over the status to understand the exact reason!

How do I unpause my webhooks?

Ensure you’re within your accounts capacity limits AND that your webhook listener responds with HTTP 200’s.

Then resume your webhook from the dashboard or via this toggle status endpoint! Your webhook will continue to stream from the latest confirmed block!

What does a “capacity limit” error mean?

The capacity limit error means you’ve exceeded your total monthly compute units. To upgrade your capacity limits, go to the billing page on your dashboard. Below is an example capacity limit error.

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

How can I debug why I’m not receiving expected webhooks?

Ensure your filters and webhooks listener are properly configured! Feel free to reach out to use on Discord for support!

Why am I missing transactions in the response?

Double check that you’re parsing the response payload correctly. Remember, transactions are returned in a list. Transactions that are mined within the same block will be returned within the same activity list.

Why are Address Activity events for the same transaction split across multiple response?

You may notice activity entries from the same transaction being split across multiple requests when using the Address Activity webhooks. This is expected behavior because webhook streams are currently separated by block and type. This means that if there are external, internal and token transfers all within the same transaction that occurred in block 49, you will still receive 3 separate webhook payloads, one for each of them.

Security and Best Practices

Find more about our security best practices here

Where can I find my Auth Token?

To find your Auth Token to use the webhook API, navigate to the webhooks dashboard, and copy the Auth Token from the top right of the page.

Where can I find my webhook’s Signing Key?

To find your signing key, navigate to the webhooks dashboard, select your webhook, and copy the singing key from the top right of that webhook’s detail page.

How do I validate the webhook event?

Every outbound request contains a hashed authentication signature in the header X-Alchemy-Signature. It’s computed by concatenating your signing key and request body. Then generates a hash using the HMAC SHA256 hash algorithm.

To verify the signature came from Alchemy, you generate the HMAC SHA256 hash and compare it with the signature received.

Example Request Header

$
POST /yourWebhookServer/push HTTP/1.1
>
Content-Type: application/json;
>
X-Alchemy-Signature: your-hashed-signature

Example Signature Validation

1
import * as crypto from "crypto";
2
3
function isValidSignatureForStringBody(
4
    body: string, // must be raw string body, not json transformed version of the body
5
    signature: string, // your "X-Alchemy-Signature" from header
6
    signingKey: string, // taken from dashboard for specific webhook
7
  ): boolean {
8
    const hmac = crypto.createHmac("sha256", signingKey); // Create a HMAC SHA256 hash using the signing key
9
    hmac.update(body, "utf8"); // Update the token hash with the request body using utf8
10
    const digest = hmac.digest("hex");
11
    return signature === digest;
12
}