Webhook Events: Metadata
The metadata webhook event provides details of a metadata stack's attributes. This event is triggered when new metadata stacks are created, as well as when existing stacks get updated through the Metadata Refresh service.
What is a metadata stack
A metadata stack is a set of metadata attributes that are shared by one or more NFTs. Each stack is distinguished by its own metadata_id.
Consider a collection of NFTs, like a set of wooden shields in a game, initially sharing the same basic metadata attributes. These basic wooden shields belong to the same metadata stack and are identified by a common metadata_id. However, as players engage in crafting actions that modify these shields' attributes, and if a metadata refresh action occurs, these modified shields are assigned a new metadata_id, thereby placing them in a different metadata stack than the original versions.
In essence, a metadata stack groups together NFTs with identical metadata attributes, and the metadata_id serves as a unique reference to distinguish one stack from another. This system allows for the tracking of metadata changes and the organisation of NFTs within a collection.
When a new asset is created, it is assigned both a token_id and a metadata_id, and this information is made available through the NFT webhook.
The below table demonstrates how metadata_id changes in different metadata update scenarios:
| Situation | Metadata Change | Metadata Refresh By | Asset After Refresh | Metadata ID |
|---|---|---|---|---|
| 1 asset with unique metadata | Update metadata | token_id | Unique metadata | New metadata_id |
| 1 asset with unique metadata | Update metadata | token_id | Asset has metadata equal to a stack of assets assigned with metadata_id=X | Refreshed asset assigned metadata_id=X |
| 1 asset with unique metadata | Update metadata | metadata_id | Unique metadata | No change to metadata_id |
| 1 asset with unique metadata | Update metadata | metadata_id | Asset has metadata equal to a stack of assets assigned with metadata_id=X | Error generated. Cannot have 2 metadata_ids representing identical stacked assets |
| 100 assets sharing metadata | Change 1 asset's metadata | token_id | Unique metadata | New metadata_id |
| 100 assets sharing metadata | Change 1 asset's metadata | token_id | Asset has metadata equal to a stack of assets assigned with metadata_id=X | Refreshed asset assigned metadata_id=X |
| 100 assets sharing metadata | Change 100 assets' metadata | metadata_id | Unique metadata for stack | No change to metadata_id |
| 100 assets sharing metadata | Change 100 assets' metadata | metadata_id | Assets has metadata equal to a stack of assets assigned with metadata_id=X | Error generated. Cannot have 2 metadata_ids representing identical stacked assets |
Once a metadata_id has been created it will persist even if there are no assets that currently have that metadata_id. If an asset is assigned metadata represented by a legacy metadata_id, it will be assigned the legacy metadata_id.
See the following example to illustrate this point:
- An unique asset has the following metadata: Animal=Dragon, Colour=Green, Strength=10 -> assigned
metadata_id=A1 - This asset has its metadata updated to the following: Animal=Dragon, Colour=Red, Strength=10 -> assigned
metadata_id=A2, no assets currently havemetadata_id=A1 - This asset has its metadata updated back to its original configuration: Animal=Dragon, Colour=Green, Strength=10 -> reassigned
metadata_id=A1
What information does the metadata webhook event provide?
Metadata plays a pivotal role in shaping the identity, attributes, and aesthetics of NFTs. It serves as a means for potential buyers to assess an asset's value, authenticity, and distinctiveness. Furthermore, metadata has a profound impact on game logic and influences various aspects of a user's gameplay experience.
A metadata_updated webhook event is triggered in two primary scenarios:
New Metadata Stack: This event occurs when a new metadata stack is created, and it is associated with a unique
metadata_id. This situation arises when a new asset with distinct metadata for a collection is minted. It can also happen when an existing asset within a metadata stack has its metadata altered, causing it to diverge from the metadata of other assets in that stack.Metadata Stack Update: In this case, the event is triggered when an existing metadata stack undergoes updates. During this event, the complete metadata stack is republished. Importantly, the
metadata_idremains the same as in the previous event related to this metadata stack.
Subscribing to this event enables the creation of a local record of an asset's metadata, as well as the establishment of mappings from token_id to metadata_id. This approach significantly reduces the need to frequently query the NFT endpoint for additional details about each asset.
Example responses
Below is an example of a metadata_updated event.
Please note for the 2 scenarios listed above, the body payload of the event will be the same except for the metadata_id, which will not be new ID for the "Metadata Stack Update" scenario.
New metadata stack published
{
"Type": "Notification",
"MessageId": "b38ab2f7-c521-5fd6-b011-ef5ea2ab043a",
"TopicArn": "arn:aws:sns:us-east-2:783421985614:webhook-outbound-sandbox",
"Message": "{\"event_name\":\"imtbl_zkevm_metadata_updated\",\"event_id\":\"018b4123-aa9e-1081-0fcc-8a5c5bd9bb63\",\"chain\":\"imtbl-zkevm-testnet\",\"data\":{\"id\":\"018b4123-aa5b-dde7-df64-b23e450cbf23\",\"chain\":{\"id\":\"eip155:13473\",\"name\":\"imtbl-zkevm-testnet\"},\"contract_address\":\"0x43c98025464e9b326be3c3782db5867073b8e78c\",\"image\":\"https://sigil.dev.x.immutable.com/0x43c98025464e9b326be3c3782db5867073b8e78c/4201\",\"external_url\":\"https://docs.opensea.io/docs/metadata-standards\",\"description\":\"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\",\"name\":\"Great Curie\",\"attributes\":[{\"trait_type\":\"Coat\",\"value\":\"Tails\"},{\"trait_type\":\"Hat\",\"value\":\"Top Hat\"},{\"trait_type\":\"Neck\",\"value\":\"Bow Tie\"}],\"animation_url\":null,\"youtube_url\":null,\"created_at\":\"0001-01-01 00:00:00\",\"updated_at\":\"0001-01-01 00:00:00\"}}",
"Timestamp": "2023-10-18T04:55:38.727Z",
"SignatureVersion": "1",
"Signature": "Y0NCgpa7MmW1hsxtFD6NvWpTICMQNF0iLiFdp/KadI4coJUphcph4WHvXJ44w7TexbWTiIF0Ot1KzMZcpPpZByV+pEN1+azh6tOsRVzF6cbmXzgs0MqCF2U0SRwKdbhH3pxOZbOZrx2Ij3IB6Bau6EN1w8pArtImUCTrDN3nB18HNXDRoufjDaMDe+AUQf5N0rzA4BzRwfobnhMsOCCTBFVBZQX75KiqPw4V8GjeYLojoULGrQuRMu1/WWQ63j8xQA6iAgAJ9MxNlMr8DxqTsAIGhnQjwBoQvEOg4l5rl1azMERDEsG844tSxuPH8phDmTj+80q0n74CUHP0oc9BWQ==",
"SigningCertURL": "https://sns.us-east-2.amazonaws.com/SimpleNotificationService-01d088a6f77103d0fe307c0069e40ed6.pem",
"UnsubscribeURL": "https://sns.us-east-2.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:us-east-2:783421985614:webhook-outbound-sandbox:3abc84aa-a8d6-413f-806b-0faf4af2add1",
"MessageAttributes": {
"chain": {
"Type": "String",
"Value": "imtbl-zkevm-testnet"
},
"collection_address": {
"Type": "String",
"Value": "0x43c98025464e9b326be3c3782db5867073b8e78c"
},
"event": {
"Type": "String",
"Value": "imtbl_zkevm_metadata_updated"
}
}
}