Chain	Mainnet	Testnet
Ethereum
Polygon
Optimism
Arbitrum

Introduction

Alchemy's Custom Webhook allows developers to stream on-chain data and get immediately notified about the most recent blockchain data changes. While previous Alchemy Notify solutions covered only pre-defined, transfers-based events, with Custom Webhooks, developers can understand any contract-based event, from token and marketplace activity, to comprehensive data ingestion. Custom Webhooks utilize a GraphQL interface so that web3 devs can have rich filters and only receive the precise blockchain data they need.

📘

TIP

If you are looking for historical blockchain activity, check out the Transfers API Endpoints.

Example Response

With Custom Webhooks utilizing a GraphQL-style interface for queries, there are an infinite number of response payload combinations. While we cannot provide an exact example for each potential query, here is one potential response that highlights the nested structure of each query originating from the block level.

{
  "webhookId": "wh_naq2hhxphyrqzmvq",
  "id": "whevt_1k0wav631jhh2hc0",
  "createdAt": "2023-03-07T18:12:21.084153908Z",
  "type": "GRAPHQL",
  "event": {
    "data": {
      "block": {
        "hash": "0xe865a371743280269c3d146b181117b15f5cd303f1f37bc644ce83f56da1a785",
        "number": 8613835,
        "timestamp": 1678205892,
        "transactions": [
          {
            "hash": "0xa579822736fb9d3736a323259a2af8d831719940b6dc58c80bf41438b76d6166",
            "nonce": 183549,
            "index": 0,
            "from": {
              "address": "0x02f84a56e4ebba0f7840aab2664ad1c8476b5ed5"
            },
            "to": {
              "address": "0x159b1ca268155e6e39e33b9b7b910e820b16802d"
            },
            "logs": [
                                    ]
          }
        ]
      }
    },
    "sequenceNumber": "10000000000578619000"
  }
}

Field Definitions

Below you can find descriptions for select response fields. Note that this is not a comprehensive list but rather a partial list that highlights the shared response fields that all Custom Webhooks will have!

How to Set Up Custom Webhooks

1. Navigate to the Notify tab in your Alchemy Dashboard and find the Custom GraphQL webhook interface
2. Click the CREATE WEBHOOK button.
3. Select your desired chain and network. NOTE: Each Custom Webhook can only be mapped to a single network/chain; if you want to have the same query applied to numerous chains, make sure to duplicate the creation process!
4. Add your unique webhook URL. This is the link to receive requests. The webhook payload might not always be compatible for 3rd party integrations. For simple visual testing, we recommend using hosted sites like requestbin or webhook.site OR spinning up a dedicated server for webhook notifications for production applications.
5. Define a GraphQL query using the dashboard playground.

If you're new to GraphQL, this editor 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 right!

6. Test and validate your GraphQL query by clicking the Test Webhook button. Confirm that your GraphQL query is valid does not contain any syntactical errors.
   NOTE: If you want to test your GraphQL query on a historical block, you can simply define your target block hash within the top-level block filter.

{
  block (hash: "0x23..... 2d1e") {
    hash,
    }
}

7. Click CREATE WEBHOOK again to submit your GraphQL filter to Alchemy. Alchemy automatically replaces the top-level block hash filter with latest so each webhook is fired for the latest canonical block!
8. Check your endpoint to see responses.

Useful Endpoints