Looking for the API Docs? Check out this page!

Alchemy Notify works by using webhooks, a way for you to subscribe to events that occur on your application. This guide will walk through what webhooks are and how you can use them in order to get started with Alchemy Notify ✅ .

What are Webhooks?

Webhooks are a way for users to receive notifications when an event occurs on your application. Rather than continuously polling the server to check if the state has changed, webhooks provide information to you as it becomes available, which is a lot more efficient and beneficial for developers. Webhooks work by registering a URL to send notifications to once certain events occur.

Webhooks are typically used to connect two different applications. One application is the "sender," which subscribes to events and sends them off to the the second "receiver" application, which takes actions based upon that received data. When an event occurs on the sender application it sends that data to the webhook URL of the receiver application. The receiver application can then send a callback message, with an HTTP status code to let the sender know the data was received successfully or not. You can think of webhook notifications just like SMS notifications. The entity sending the message has your registered phone number and they send a specific message payload to that phone number. You then have the ability to respond confirming you have received it, creating a two-way communication stream.

Types of Webhooks

Alchemy offers four different types of webhooks described below.

1. Mined Transactions

The Mined Transaction Webhook is used to notify your app anytime a transaction gets successfully mined. This is extremely useful if you want to notify customers the moment their transactions goes through.

Example Response

{
  "app": "Demo", 
  "network": "MAINNET",
  "webhookType": "MINED_TRANSACTION",
  "fullTransaction": {
    "hash": "0x5a4bf6970980a9381e6d6c78d96ab278035bbff58c383ffe96a0a2bbc7c02a4b",
    "blockHash": "0xaa20f7bde5be60603f11a45fc4923aab7552be775403fc00c2e6b805e6297dbe",
    "blockNumber": "0x989680",
    "from": "0x8a9d69aa686fa0f9bbdec21294f67d4d9cfb4a3e",
    "gas": "0x5208",
    "gasPrice": "0x165a0bc00",
    "input": "0x",
    "nonce": "0x2f",
    "r": "0x575d26288c1e3aa63e80eea927f54d5ad587ad795ad830149837258344a87d7c",
    "s": "0x25f5a3abf22f5b8ef6ed307a76e670f0c9fb4a71fab2621fce8b52da2ab8fe82",
    "to": "0xd69b8ff1888e78d9c337c2f2e6b3bf3e7357800e",
    "transactionIndex": "0x66",
    "v": "0x1c",
    "value": "0x1bc16d674ec80000"
  },
  "timestamp": "2020-07-29T00:29:18.414Z"
}

2. Dropped Transactions

The Dropped Transactions Webhook is used to notify your app anytime a transaction gets dropped.

Example Response

{
  "app": "Alchemy Mainnet",
  "network": "MAINNET",
  "webhookType": "DROPPED_TRANSACTION",
  "hash": "0x8f2fbdf411ed403034979343d5ee86e6d9a6d6b6599878c865291b75fb3432b1",
  "timestamp": "2020-06-08T22:12:57.126Z",
  "fullTransaction": {
    "hash": "0x5a4bf6970980a9381e6d6c78d96ab278035bbff58c383ffe96a0a2bbc7c02a4b",
    "blockHash": null,
    "blockNumber": null,
    "from": "0x8a9d69aa686fa0f9bbdec21294f67d4d9cfb4a3e",
    "gas": "0x5208",
    "gasPrice": "0x165a0bc00",
    "input": "0x",
    "nonce": "0x2f",
    "r": "0x575d26288c1e3aa63e80eea927f54d5ad587ad795ad830149837258344a87d7c",
    "s": "0x25f5a3abf22f5b8ef6ed307a76e670f0c9fb4a71fab2621fce8b52da2ab8fe82",
    "to": "0xd69b8ff1888e78d9c337c2f2e6b3bf3e7357800e",
    "transactionIndex": null,
    "v": "0x1c",
    "value": "0x1bc16d674ec80000"
  }
}

3. Address Activity

The Address Activity Webhook allows you to track all ETH, ERC20 and ERC721 transfer events for as many Ethereum addresses as you'd like. This provides your app with real-time state changes when an address sends or receives tokens.

If you are looking for historical activity, check out the Transfers API!

Example Response

{
  "app": "Test webhooks",
  "network": "MAINNET",
  "webhookType": "ADDRESS_ACTIVITY",
  "timestamp": null,
  "activity": [
    {
      "fromAddress": "0x000000000000000000000000861919405ff21a566ae33702d508ed0bfce13afc",
      "toAddress": "0x000000000000000000000000fdb16996831753d5331ff813c29a93c76834a0ad",
      "blockNum": "0xa4a152",
      "hash": "0x903b87c128044b6142dcb8e0df52d43a2c916fb7510a4105e9874c53f764ee1f",
      "category": "token",
      "value": 21000,
      "asset": "USDT",
      "rawContract": {
        "rawValue": "0x00000000000000000000000000000000000000000000000000000004e3b29200",
        "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
        "decimals": 6
      }
    },
    {
      "fromAddress": "0x000000000000000000000000a075d6d8a643ea36a2a26fb73c5c6bfa038c182f",
      "toAddress": "0x000000000000000000000000fdb16996831753d5331ff813c29a93c76834a0ad",
      "blockNum": "0xa4a152",
      "hash": "0x2970ce0061f4cb816bd121837b5f65264a97d198b40771e1199dab57b93d860d",
      "category": "token",
      "value": 10000,
      "asset": "USDT",
      "rawContract": {
        "rawValue": "0x00000000000000000000000000000000000000000000000000000002540be400",
        "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
        "decimals": 6
      }
    }
  ]
​
}

4. Gas Price

The Gas Price Webhook allows you to receive a notification every minute when the Mainnet gas price rises above or drops below a certain threshold that you can select. It works by pulling the current gas prices from ETH Gas Station every minute.

Gas prices typically fall in a range, where a lower gas price means that the transaction will take longer to be mined, and a higher gas price means that the transaction will be mined more quickly. The Execution Speed metric allows you to specify a metric in that range that you would like to receive notifications, corresponding to ETH Gas Station's Price Type metric documented here. For example, selecting an Average Execution Speed means that you will receive notifications when a gas price typically mined in under 5 minutes rises above or drops below your selected threshold

Example Response

{
  "app": "Alchemy Mainnet",
  "network": "MAINNET",
  "timestamp": "2020-09-09T15:14:19.175Z",
  "gasPriceMetadata": {
    "fast": 160,
    "fastest": 167,
    "safeLow": 147,
    "average": 150,
    "block_time": 11.894736842105264,
    "blockNum": 10828228,
    "speed": 0.9968284026882861,
    "safeLowWait": 14.6,
    "avgWait": 3.9,
    "fastWait": 0.4,
    "fastestWait": 0.4
  }
}

Test Out Webhooks

There are many websites you can use to test out webhooks. For example, you can use https://webhook.site/ and copy your unique URL. Once you have the URL, you can test using the following steps:

1. Navigate to your Notify dashboard​

2. Click "Create Webhook" on the webhook you want to test

3. Specify which app you wish to add notifications to

4. Paste in your unique URL and hit the "Test Webhook" button

You should then see the result updated on website: https://webhook.site/​

How to Set Up Webhooks

Setting up a webhook is as simple as adding a new URL to your application. There are two primary ways to activate webhooks: 1) through the Notify dashboard and 2) through an API request.

The following steps are for creating a webhook through your Alchemy dashboard. To set up webhooks through an API call, check out our Notify API Reference page.

Setting Up Webhooks from the Dashboard

1. Navigate to the Notify tab in your Alchemy Dashboard​

2. Determine which type of webhook you want to activate

3. Click the "Create Webhook" button

4. Specify which app you wish to add notifications to

5. Add in your unique webhook URL, this can be any link that you want to receive requests at (your server, slack, etc.)

6. Test out your webhook by hitting the "Test Webhook" button to ensure it works properly

7. Hit "Create Webhook" and you should then see your webhook appear in the list!

8. Check your endpoint to see responses rolling through

Capacity Limit

If you receive a capacity limit error, meaning you have exceeded your total monthly compute units, you should receive a response similar to the one below. You can upgrade your scaling policy on the Alchemy dashboard.​

{
  "app": "Demo",
  "network": "MAINNET",
  "error": "Monthly capacity limit exceeded. Upgrade your scaling policy for continued service.",
  "webhookType": "MINED_TRANSACTION",
  "timestamp": "2020-07-29T01:13:54.703Z"
}

Webhook Signature and Security

If you want to make your webhooks extra secure, you can verify that they originated from Alchemy by generating a HMAC SHA-256 hash code using your Authentication Token and request body.

1. Find your Authentication Token

Navigate to the top right corner of your Notify page to copy your "Auth Token".

2. Validate the signature received

Every outbound request will contain a hashed authentication signature in the header which is computed by concatenating your auth token and request body then generating a hash using the HMAC SHA256 hash algorithm.

In order to verify this signature came from Alchemy, you simply have to 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 Function

function isValidSignature(request) {    
    const token = 'Auth token provided by Alchemy on the Webhook setup page';
    const headers = request.headers;
    const signature = headers['x-alchemy-signature']; // Lowercase for NodeJS
    const body = request.body;    
    const hmac = crypto.createHmac('sha256', token) // Create a HMAC SHA256 hash using the auth token
    hmac.update(body, 'utf8') // Update the token hash with the request body using utf8
    const digest = hmac.digest('hex');     
    return (signature === digest); // If signature equals your computed hash, return true
}