Alchemy Webhooks let you receive real-time HTTP POST requests for on-chain events across 80+ chains — no polling required! They’re often used to stream:

• all on-chain activity for millions of wallets
• events and traces for any smart contract
• all block data (including traces)

They’re also fully customizable via a GraphQL style query.

Why Alchemy Webhooks?

• ⛓️ Multi-Chain: Supports over 80+ EVM chains (+ Solana now) and more soon
• ⚡ Fast: Streams on-chain events immediately as blocks confirm
• 💪🏽 Reliable: Built on our propietary blockchain engine, and incudes retries
• 🧑‍🤝‍🧑 Scalable: Tracks millions of users effortlessly
• 💰 Savings: Reduces RPC spend by eliminating polling workflows

Webhook types

Custom Webhooks	Address Activity	NFT Activity
Ideal for: Most Use Cases How it works: Get notified for any event on every block	Ideal for: Wallets, Portfolio Trackers How it works: Get notified when an address transacts	Ideal for: NFT Collections, NFT Analytics How it works: Get notified when NFTs are transferred

Webhook Payload Structure

Field definitions

Example

$
{
>
 "webhookId": "wh_octjglnywaupz6th",
>
 "id": "whevt_ogrc5v64myey69ux",
>
 "createdAt": "2021-12-07T03:52:45.899Z",
>
 "type": TYPE_STRING,
>
 "event": OBJECT
>
}

Getting Started

To start building with webhooks:

1. Select the right webhook type
2. Create a webhook listener
3. Create and test your webhook

Select the right webhook type

• If you’re interested in tracking transfers on a set of wallets, (< 100K wallets), get started with our Address Activity webhooks!
• If you’re interested in tracking transfers of a particular NFT, an NFT collection, or all NFTs for a chain, use the NFT Activity webhooks!
• For all other use cases, we recommend leveraging our Custom webhooks!

Create a webhook listener

Webhook listeners receive requests and process event data.

The listener responds to the Alchemy server with a 200 status code once it successfully receives the webhook event. Your webhook listener can be a simple server or Slack integration to receive the webhook listener data.

After setting up the webhooks in your Alchemy dashboard (or programmatically) use the starter code in JavaScript, Python, Go, and Rust below. Here’s the GitHub repository for the entire code.

1
import express from "express";
2
import { getRequiredEnvVar, setDefaultEnvVar } from "./envHelpers";
3
import {
4
  addAlchemyContextToRequest,
5
  validateAlchemySignature,
6
  AlchemyWebhookEvent,
7
} from "./webhooksUtil";
8
9
async function main(): Promise<void> {
10
  const app = express();
11
12
  setDefaultEnvVar("PORT", "8080");
13
  setDefaultEnvVar("HOST", "127.0.0.1");
14
  setDefaultEnvVar("SIGNING_KEY", "whsec_test");
15
16
  const port = +getRequiredEnvVar("PORT");
17
  const host = getRequiredEnvVar("HOST");
18
  const signingKey = getRequiredEnvVar("SIGNING_KEY");
19
20
  // Middleware needed to validate the alchemy signature
21
  app.use(
22
    express.json({
23
      verify: addAlchemyContextToRequest,
24
    })
25
  );
26
  app.use(validateAlchemySignature(signingKey));
27
28
  // Register handler for Alchemy Notify webhook events
29
  // TODO: update to your own webhook path
30
  app.post("/webhook-path", (req, res) => {
31
    const webhookEvent = req.body as AlchemyWebhookEvent;
32
    // Do stuff with with webhook event here!
33
    console.log(`Processing webhook event id: ${webhookEvent.id}`);
34
    // Be sure to respond with 200 when you successfully process the event
35
    res.send("Alchemy Webhooks are the best!");
36
  });
37
38
  // Listen to Alchemy Notify webhook events
39
  app.listen(port, host, () => {
40
    console.log(`Example Alchemy Webhooks app listening at ${host}:${port}`);
41
  });
42
}
43
44
main();

Create and test your webhooks

1. Navigate to the webhooks dashboard and click Create Webhook OR create one by calling the createWebhook endpoint. When it asks for your Webhook URL, enter your endpoint or follow these steps to create an NGROK endpoint:

   • Sign-up for a free Ngrok account.
   • Install Ngrok using the Ngrok guide. On macOS run brew install ngrok.
   • Connect your Ngrok account by running ngrok authtoken YOUR_AUTH_TOKEN.
   • Start your local forwarding tunnel: ngrok http 80.

2. Once you have a URL to test your webhook (in this case https://461a-199-116-73-171.ngrok.io pictured above), paste your NGROK endpoint into the Webhook URL field and hit “Test Webhook”, and see the event appear here: http://localhost:4040/inspect/http

3. Navigate to your webhooks dashboard.

4. Click Create Webhook on the webhook you want to test.

5. Paste your unique URL and hit the Test Webhook button.

6. You’ll see the webhooks here: http://localhost:4040/inspect/http.

Webhook Signature & Security

Signatures

To make your webhooks secure, you can verify that they originated from Alchemy by generating a HMAC SHA-256 hash code using your unique webhook signing key.

Find your 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.

Validate the signature received

Every outbound request contains a hashed authentication signature in the header. 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
}

Auth Token

The Auth Token, located at the top of you webhooks dashboard, is required to let you manage your webhooks via our webhooks API!

Webhooks IP addresses

As an added security measure, you can ensure your webhook notification originates from Alchemy by using one of the following IP addresses:

• 54.236.136.17
• 34.237.24.169

Webhook Delivery Behavior

• Event Ordering - All first-time webhooks notifications, regardless of the selected chain/network and its speed, will be delivered in order to users.
• Automatic Retries - Webhooks have built-in retry-logic with exponential backoff for non-200 response codes in failures to reach your server. For Free and PAYG 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.
• Manual Retries (Coming Soon) - Soon you’ll have the ability to manually trigger retries for failed events!