Webhook Events: Common Use Cases

Immutable's Blockchain Data Webhooks integrations empower partners to track specific events or synchronise local databases without the need for continuous requests to Immutable's APIs for updates. Here are some common use cases that occur on the platform, and the respective events that are triggered.

Common use cases and associated events

When a player or game studio engages in activities on the platform, a series of webhook events are generated to accurately depict these actions.

Presented below is a list of prevalent use cases that partners frequently monitor. This guide aims to assist you in discerning which specific events to subscribe to, aligning your choices with your precise tracking requirements.

New NFT created with new metadata (unique to a collection)

When a new NFT is minted from a collection, and that NFT has unique metadata within the collection that requires a new metadata_id, the following events occur:

• imtbl_zkevm_activity_mint: The event contains collection_address and token_id, but no metadata. The NFT owner's wallet address is also included in these messages.
• nft_updated: The event includes collection_address and token_id, but does not include owner details. Metadata will not have been indexed yet, so no metadata_id will be present.
• nft_updated: The event includes collection_address , token_id and metadata_id, but does not include owner details or metadata attributes. This event can be used to map token_id to an asset's metadata_id. metadata_id will be unique.
• metadata_updated: The event includes collection_address and introduces a new unique metadata_id to represent a new metadata stack.

New NFT created with metadata that matches an existing stack of the collection

When a new NFT is minted from a collection, and that NFT is a duplicate of another asset that has been previously minted, they will share an existing metadata_id. This is represented in the following way:

• imtbl_zkevm_activity_mint: The event contains collection_address and token_id, but no metadata. The NFT owner's wallet address is also included in these messages.
• nft_updated: The event includes collection_address and token_id, but does not include owner details. Metadata will not have been indexed yet, so no metadata_id will be present.
• nft_updated: The event includes collection_address , token_id and metadata_id, but does not include owner details or metadata attributes. This event can be used to map token_id to an asset's metadata_id. metadata_id will be from a previously notified metadata stack.

NFT with unique metadata is updated (i.e. No other NFT in that collection shares the same metadata attributes)

When the Metadata Refresh service updates the metadata for a unique asset (Metadata Refresh via token_id) that doesn't share its metadata_id with any other NFT, the following events occur:

• nft_updated: The event includes collection_address, token_id and metadata_id, but does not include owner details or metadata attributes. The metadata_id for this NFT will change as a result of it's metadata being updated.
• metadata_updated: This event includes collection_address, metadata_id, and all metadata attributes. The metadata_id assigned will be new if the NFT's metadata is unique (i.e. post metadata change, the NFT has metadata attributes that no other NFT of the same collection has). If the metadata is not unique, no metadata_updated message will be sent as the nft_updated message will assign the NFT to an existing metadata_id.

Single NFT with non-unique metadata is updated (i.e. NFT has the exact same metadata attribute as other NFTs in the same collection)

When the Metadata Refresh service updates the metadata for a non-unique asset (Metadata Refresh via token_id), and this asset (pre-change) shares its metadata_id with others that haven't had their metadata updated, the following events take place (note: The NFTs that do not have their metadata change as a result of the refresh activity will not be changed. The metadata_id for these assets will not change, nor will the metadata attributes associated with this ID):

• nft_updated: The event includes collection_address, token_id and metadata_id, but does not include owner details or metadata attributes. The metadata_id will be updated from previous events for this NFT.
• metadata_updated: This event includes collection_address, metadata_id, and all metadata attributes. The metadata_id assigned will be new if the NFT's metadata is unique (i.e. post metadata change, the NFT has metadata attributes that no other NFT of the same collection has). If the metadata is not unique, no metadata_updated message will be sent as the nft_updated message will assign the NFT to an existing metadata_id.

Stack of NFTs with the same metadata is updated

When the Metadata Refresh service updates the metadata an entire stack of metadata (Metadata Refresh via metadata_id) the following events take place (note: No nft_updated event occurs):

• metadata_updated: This event contains collection_address and all metadata attributes, whether changed or not. The metadata_id remains the same as in the previous metadata_updated event for the asset.

New order (listing) placed on a marketplace

When a player lists an NFT on a 3rd party marketplace, two order_updated events occur:

• order_updated (Pending): This event includes a collection_address, token_id, and order_id but lacks a metadata_id. The order's status is marked as PENDING because Immutable has not yet confirmed the seller's balance. To access the asset's metadata attributes, you can refer to a previous metadata_updated message stored in your application's backend or use the NFT endpoint.
• order_updated (Active): This event includes a collection_address, token_id, and order_id, but no metadata_id. The order's status is now ACTIVE and live because Immutable has confirmed that the seller has the advertised balance. To access the asset's metadata attributes, you can refer to a previous metadata_updated message stored in your application's backend or use the NFT endpoint.

New trade executed

When an NFT is listed on one marketplace and then transferred to another player, the following events occur:

• imtbl_zkevm_activity_sale: This event includes details like collection_address, token_id, order_id, and trade_id, but not metadata_id. It provides wallet addresses of the buyer and seller along with trade information. The asset's metadata attributes from a previous metadata_updated message stored in your app's backend or by using the NFT endpoint.
• trade_created: This event includes details like collection_address, token_id, order_id, and trade_id, but not metadata_id. It provides wallet addresses of the buyer and seller along with trade information. The asset's metadata attributes from a previous metadata_updated message stored in your app's backend or by using the NFT endpoint.
• order_updated (Filled): This event contains a collection_address, token_id and order_id but no metadata_id. The status of the order will be FILLED.