Custom Webhook

Track any smart contract or marketplace activity, monitor any contract creation, or ingest any other on-chain interaction. Infinite data access with precise filter controls.

Base:white-check-mark:; no internal transaction support yet:white-check-mark:; no internal transaction support yet


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.



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!

webhookIdUnique ID of the webhook destination.wh_octjglnywaupz6th
idID of the event.whevt_ogrc5v64myey69ux
createdAtTimestamp when the webhook was created.2022-02-28T17:48:53.306Z
typeWebhook event type.GRAPHQL
eventNested block/transaction/log object.N/A
blockNested object under each blockN/A
sequenceNumberAn incrementing integer used for client-side re-org handling.10000000000578619000

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 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!

  1. 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") {
  1. 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!
  2. Check your endpoint to see responses.

Useful Endpoints

Create WebhookThis endpoint allows you to create a webhook programatically.
Delete WebhookAllows you to delete a webhook.
Get All WebhooksAllows you to get all instantiated webhooks.