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
andtoken_id
, but no metadata. The NFT owner's wallet address is also included in these messages. - nft_updated: The event includes
collection_address
andtoken_id
, but does not include owner details. Metadata will not have been indexed yet, so nometadata_id
will be present. - nft_updated: The event includes
collection_address
,token_id
andmetadata_id
, but does not include owner details or metadata attributes. This event can be used to maptoken_id
to an asset'smetadata_id
.metadata_id
will be unique. - metadata_updated: The event includes
collection_address
and introduces a new uniquemetadata_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
andtoken_id
, but no metadata. The NFT owner's wallet address is also included in these messages. - nft_updated: The event includes
collection_address
andtoken_id
, but does not include owner details. Metadata will not have been indexed yet, so nometadata_id
will be present. - nft_updated: The event includes
collection_address
,token_id
andmetadata_id
, but does not include owner details or metadata attributes. This event can be used to maptoken_id
to an asset'smetadata_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
andmetadata_id
, but does not include owner details or metadata attributes. Themetadata_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. Themetadata_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, nometadata_updated
message will be sent as thenft_updated
message will assign the NFT to an existingmetadata_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
andmetadata_id
, but does not include owner details or metadata attributes. Themetadata_id
will be updated from previous events for this NFT. - metadata_updated: This event includes
collection_address
,metadata_id
, and all metadata attributes. Themetadata_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, nometadata_updated
message will be sent as thenft_updated
message will assign the NFT to an existingmetadata_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. Themetadata_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
, andorder_id
but lacks ametadata_id
. The order'sstatus
is marked asPENDING
because Immutable has not yet confirmed the seller's balance. To access the asset's metadata attributes, you can refer to a previousmetadata_updated
message stored in your application's backend or use the NFT endpoint. - order_updated (Active): This event includes a
collection_address
,token_id
, andorder_id
, but nometadata_id
. The order'sstatus
is nowACTIVE
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 previousmetadata_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
, andtrade_id
, but notmetadata_id
. It provides wallet addresses of the buyer and seller along with trade information. The asset's metadata attributes from a previousmetadata_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
, andtrade_id
, but notmetadata_id
. It provides wallet addresses of the buyer and seller along with trade information. The asset's metadata attributes from a previousmetadata_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
andorder_id
but nometadata_id
. Thestatus
of the order will beFILLED
.