Skip to main content

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.

Metadata webhook event detailsMetadata webhook event details

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:

SituationMetadata ChangeMetadata Refresh ByAsset After RefreshMetadata ID
1 asset with unique metadataUpdate metadatatoken_idUnique metadataNew metadata_id
1 asset with unique metadataUpdate metadatatoken_idAsset has metadata equal to a stack of assets assigned with metadata_id=XRefreshed asset assigned metadata_id=X
1 asset with unique metadataUpdate metadatametadata_idUnique metadataNo change to metadata_id
1 asset with unique metadataUpdate metadatametadata_idAsset has metadata equal to a stack of assets assigned with metadata_id=XError generated. Cannot have 2 metadata_ids representing identical stacked assets
100 assets sharing metadataChange 1 asset's metadatatoken_idUnique metadataNew metadata_id
100 assets sharing metadataChange 1 asset's metadatatoken_idAsset has metadata equal to a stack of assets assigned with metadata_id=XRefreshed asset assigned metadata_id=X
100 assets sharing metadataChange 100 assets' metadatametadata_idUnique metadata for stackNo change to metadata_id
100 assets sharing metadataChange 100 assets' metadatametadata_idAssets has metadata equal to a stack of assets assigned with metadata_id=XError 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:

  1. An unique asset has the following metadata: Animal=Dragon, Colour=Green, Strength=10 -> assigned metadata_id=A1
  2. This asset has its metadata updated to the following: Animal=Dragon, Colour=Red, Strength=10 -> assigned metadata_id=A2, no assets currently have metadata_id=A1
  3. 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:

  1. 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.

  2. 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_id remains 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"
}
}
}