Blockchain Data APIs - Webhooks
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. These events are proactively pushed from Immutable's platform.
What are webhooks?
Webhooks are a method for web applications to communicate with each other in real-time. They are automated messages or notifications sent from one system to another when a particular event occurs. Essentially, webhooks allow one application to inform another about an event, triggering an immediate action or response.
Webhooks is preferred over continuous polling for the following reason:
Real-time Updates: Webhooks provide real-time updates. When an event occurs, the webhook immediately triggers an action in the receiving application. This is in contrast to polling, which involves repeatedly checking for updates at predefined intervals.
Efficiency: Polling can be inefficient, especially when there are no updates. It requires regular requests to the API, even when there's no new data. In contrast, webhooks are event-driven, meaning they only send data when an event occurs, reducing unnecessary traffic and load on the server.
Reduced Latency: Webhooks minimise latency. Since they send updates in real-time, you get the latest data as soon as it becomes available. With polling, you may experience delays depending on the polling frequency.
Simplicity: Setting up a webhook involves configuring the source application to send data to a specified endpoint. Polling, on the other hand, requires writing and maintaining code to periodically query an API, making it more complex.
Overall, webhooks in Web3 gaming provide a mechanism for real-time communication and data synchronisation, enabling a more dynamic and engaging gaming experience while also enhancing the operational efficiency of blockchain-based games.
What can webhooks be used for?
In Web3 gaming, webhooks can be used for various purposes to enhance the gaming experience and streamline operations. Common use cases are as follows:
Real-Time Game Events: Webhooks serve as a powerful tool for delivering real-time notifications to players, game servers, or other applications whenever partner requested on-chain asset-related events occur. For example if certain events are dependent on assets being minted, transferred, burnt or their metadata is updated; webhooks are an efficient way for partners applications to be alerted that these events have occurred.
Marketplace Updates: Webhooks keep 3rd-party marketplaces informed about the status of in-game assets listed on multiple platforms. They receive instant updates when items are listed or sold elsewhere, ensuring accurate inventory management for traders and collectors.
Analytics and Metrics: Webhooks can send game-related data to analytics platforms, enabling game developers to track player behaviour, identify trends, and make data-driven decisions for game improvements.
Synchronising Databases: Webhooks enable 3rd parties to keep a local copy of Immutable's Blockchain Data API database. External databases can mirror Immutable's records through being notified when events occur that change the status of assets, tokens or collections.
How to setup webhooks?
Follow our setup guide how to set up webhooks for your application
Event subscriptions
The following events can be requested through a single webhook connection:
| Event Group | Event Type | Description |
|---|---|---|
| Activities | imtbl_zkevm_activity_mint; imtbl_zkevm_activity_burn; imtbl_zkevm_activity_transfer; imtbl_zkevm_activity_sale; imtbl_zkevm_activity_deposit; imtbl_zkevm_activity_withdrawal | This event provides details on minting (NFT), transferring (NFT), burning (NFT), trading (NFT), withdrawals (ERC20) and deposits (ERC20) on Immutable's zkEVM blockchain. These events are great for tracking NFT ownership changes, as well as monitoring blockchain activity to trigger updates to your application. No metadata is contained within these event types. |
| Collections | imtbl_zkevm_collection_updated | This event signals when a collection is created or modified. The collection's metadata is present in this payload of these events. |
| NFT | imtbl_zkevm_nft_updated | This event signals when an NFT is created or modified. It includes token_id to metadata_id mappings, which link metadata stacks to each NFT. When used in conjunction with the metadata_updated event, it enables the mapping of assets to their respective metadata, providing a comprehensive view of NFTs and their associated metadata within Immutable's ecosystem. |
| Mint Requests | imtbl_zkevm_mint_request_updated | This event signals when a mint request via the Minting API is performed, and when the mint is completed. It includes reference_id to token_idmappings, which the content creators minting request with the system generatedtoken_id` provided when an NFT is successfully minted. |
| Metadata | imtbl_zkevm_metadata_updated | This event provides details of a metadata stack's attributes, with each stack being defined by a unique metadata_id. This event is triggered when new metadata stacks are created, as well as when existing stacks get updated through the Metadata Refresh service. |
| Tokens | imtbl_zkevm_token_updated | This event signals when a new ERC20 token is deployed on Immutable's zkEVM platform. |
| Orders | imtbl_zkevm_order_updated | This event signals when a new order (listing) is placed on a 3rd party marketplace. Orders are centralised through Immutable's central orderbook. |
| Trades | imtbl_zkevm_trade_created | This event signals when a trade occurs on Immutable's Global Orderbook. The details of the trade are present, including additional fees. |
The updated event captures both "creation" or "updating" of an entity. Whenever an updated event is received, it should be treated as an "upsert", i.e. create the entity if it does not exist, otherwise update it.
The created event for trades represents that the action is in its finalised state; which means it is immutable.
For information regarding our Immutable X events please refer to our Immutable X Webhooks documentation.
Event message content
Webhook events will adhere to the following message format:
- Event_name: The event that triggered the notification
- Event_id: The unique identifier of the event
- Chain: The Immutable rollup where the event occurred
- Data: The latest state of the underlying entity
How does this work in practice?
Please refer to our detailed guide that highlights common use cases that are effectively represented by webhook events. This resource will provide you with valuable insights into the various scenarios and actions covered by these events, assisting you in making informed decisions regarding your event subscriptions.