If you’re a developer building an application or service that requires real time updates on NFT data and transactions, obtaining reliable, timely sources is challenging for a number of reasons.
First, NFT activity is moving across chains, requiring developers to interface with the different ways that each chain (including L1s, L2s, and side-chains) implement NFT standards. Even with a working implementation for a given chain, querying the current state of NFT data requires multiple steps:
Second, beyond basic metadata and transfers, obtaining detailed information on the sales of NFTs is even more complicated: some marketplaces conduct off-chain sales, and each NFT sales contract has a different implementation to consider.
Finally, developers must also decide on the querying method to obtain this data. Polling an endpoint interfaced with a node provider is one option, but this approach also comes with a scoping challenge – a developer may only be interested in the events for a specific wallet, or contract, and filtering the entire set of events from a chain will be inefficient.
For this use case, where obtaining events in real time is important, and polling would be inefficient or not feasible, a webhook may be the right choice.
At SimpleHash, we’ve built a stable and reliable webhook service to deliver NFT events in real-time, abstracting away these challenges.
Using the webhook API, developers can subscribe to multiple types of events, including:
Subscribing to these events is easy, and flexible, with the ability to specify multiple wallet addresses, nfts, contracts, or chains per webhook subscription, depending on the developer’s use case.
Once set up, developers will receive an ongoing stream of updates, based on the parameters chosen. There’s no need to worry about the underlying implementation of NFT data, to build custom logic for different chains, or to continually re-poll for the latest data.
In the next section, we’ll walk through setting up a basic webhook to stream metadata updates on a given NFT contract.
What is meant by a “metadata update”? Many NFTs have pointer URIs within their on-chain data that reference off-chain metadata. This metadata can be nearly anything, but it typically contains additional context or information about the NFT, such as a link to a media file, key value pairs, or a json object. A metadata update refers to a change in this off-chain metadata information.
For example, the CloneX NFT, with token ID 5142, on contract address 0x49cf6f5d44e70224e2e23fdcdd2c053f30ada28b, on ethereum contains multiple key value pairs describing its traits (hair, clothing, etc), and a link to its original media file, located at https://clonex-assets.rtfkt.com/images/5142.png. For many NFT collections, metadata can change over time, or be dynamic, depending on their purpose or type (collectible, an in-game item, a quest reward, etc).
The next section assumes some familiarity with modern web and server frameworks, but should only take a few minutes to get up and running, and streaming metadata updates.
The first step is to have an endpoint ready in your client application to accept inbound events. This can be set up using any framework you like, but it should be able to accept POST requests. (e.g. https://examplenftapplication.com/webhook_receiver).
Next, if you don’t have one already, you’ll need a SimpleHash API key, which can be obtained for free from the SimpleHash developer portal.
Next is creating the webhook subscription. The API documentation for doing so can be found here, but to break it down:
curl –request POST \
–url https://api.simplehash.com/webhook_api/v0/webhook \
–header ‘X-API-KEY: ${YOUR_API_KEY} \
–header ‘accept: application/json’ \
–header ‘content-type: application/json’ \
–data ‘
{
“webhook_url”: “https://example.com/webhook_listener”,
“event_types”: [
“contract.nft_metadata_update”
],
“contract_addresses”: [
“ethereum.0x495f947276749ce646f68ac8c248420045cb7b5e”
],
“webhook_secret”: “d3pxazhtNnhnaBHuN3FhTJX0aDZh7mxj”
}
We’re also including a webhook secret parameter, which is best practice for ensuring the security of streamed events. (More info about this can be found here)
Assuming a successful 200 response from your POST request, your webhook subscription will be set up, and you will start receiving events at the specified endpoint. The payload for events being streamed will look similar to this:
For NFT metadata updates, they will be sent anytime any of the following fields on an NFT changes:
If you need to list, update, or delete your webhook subscription, that’s also easy to accomplish.
With this webhook subscription setup, you can use the data in any which way that makes sense for your application. NFT metadata updates are useful for building a wide range of different applications, including:
There are plenty of other potential use cases – and if you’re building in the space, or have plans to do so, please get in touch. The goal for the SimpleHash webhook API is to provide developers with the easiest, most reliable solution for streaming real time NFT-related events. We love chatting with builders and projects in the space – if you have more questions about the webhook API (or the SimpleHash platform overall), say hi at hello@simplehash.com.