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.
Chain | Mainnet | Testnet |
---|---|---|
Ethereum | ![]() | ![]() |
Polygon | ![]() | ![]() |
Optimism | ![]() | ![]() |
Arbitrum | ![]() | ![]() |
Base | ![]() | ![]() |
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!
Field | Description | Value |
---|---|---|
webhookId | Unique ID of the webhook destination. | wh_octjglnywaupz6th |
id | ID of the event. | whevt_ogrc5v64myey69ux |
createdAt | Timestamp when the webhook was created. | 2022-02-28T17:48:53.306Z |
type | Webhook event type. | GRAPHQL |
event | Nested block/transaction/log object. | N/A |
block | Nested object under each block | N/A |
sequenceNumber | An incrementing integer used for client-side re-org handling. | 10000000000578619000 |
How to Set Up Custom Webhooks
- Navigate to the Notify tab in your Alchemy Dashboard and find the Custom GraphQL webhook interface
- Click the CREATE WEBHOOK button.
- 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!
- 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.
- 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!
- 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,
}
}
- 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!
- Check your endpoint to see responses.
Useful Endpoints
Endpoint | Description |
---|---|
Create Webhook | This endpoint allows you to create a webhook programatically. |
Delete Webhook | Allows you to delete a webhook. |
Get All Webhooks | Allows you to get all instantiated webhooks. |