Skip to main content

Webhook Events: Orders

The orders webhook event signals when a new order (listing) is placed. Orders are centralised through Immutable's Global Orderbook.

Sections
Orders webhook event detailsOrders webhook event details

What information does the orders webhook event provide?​

The imtbl_zkevm_order_updated event is triggered when a new order is placed or cancelled. Marketplaces use this event to list orders for assets that were submitted on other marketplaces through Immutable's Global Orderbook. This event provides comprehensive information about the order, including order id, token_id, price, currency, and associated fees. It serves as a valuable tool for tracking and managing orders across different marketplaces within Immutable's ecosystem.

No asset metadata is provided in the imtbl_zkevm_order_updated event; the following workflows are available to determine an order's metadata:

  1. Backend Integration: Use your local application's backend to keep track of metadata attributes and token_id to metadata_id mappings. These can be found by subscribing to NFT and Metadata events.
  2. API Polling: Use the Blockchain Data API NFT endpoint using token_id to review the assets metadata attributes.

Example responses​

Below are some examples of imtbl_zkevm_order_updated events for common use-cases:

note

Orders cannot be amended, they must be cancelled and then re-submitted with new details For further details on order statuses, see the following product guide

Orders containing ERC1155 tokens can be partially filled. The fill_status field in the order_updated event payload will indicate the ratio of the order that is currently filled. If the order has not been filled at all, the numerator and denominator values of the fill_status field will be 0. If the order has been fully filled, the numerator and denominator values will be equal.

For instance, the below snipped would indicate that 50% of the order has been filled.

"fill_status": {
  "numerator": "1",
  "denominator": "2"
}
note

For further details on order fill status, see the following product guide

New NFT order​

The initial order prior to the balance being confirmed by Immutable:

{
    "event_name": "imtbl_zkevm_order_updated",
    "event_id": "018b3ac9-a2df-d8d3-1a5a-2e2ac158ae59",
    "chain": "imtbl-zkevm-testnet",
    "data": {
        "type": "LISTING",
        "id": "018b3ac9-a2c3-c153-8c18-01902b663abb",
        "chain": {
            "id": "eip155:13473",
            "name": "imtbl-zkevm-testnet"
        },
        "account_address": "0xc606830d8341bc9f5f5dd7615e9313d2655b505d",
        "buy": [
            {
                "type": "NATIVE",
                "amount": "1000000"
            }
        ],
        "sell": [
            {
                "type": "ERC721",
                "contract_address": "0xfdee4926d1a7b01cc1b8d086faf0b2194c99acc8",
                "token_id": "1"
            }
        ],
        "fees": [
            {
                "type": "MAKER_ECOSYSTEM",
                "amount": "1",
                "recipient": "0xc606830d8341bc9f5f5dd7615e9313d2655b505d"
            },
            {
                "type": "PROTOCOL",
                "amount": "20000",
                "recipient": "0x9a48b1b27743d807331d06ecf0bfb15c06fdb58d"
            },
            {
                "type": "ROYALTY",
                "amount": "10000",
                "recipient": "0x9a48b1b27743d807331d06ecf0bfb15c06fdb58d"
            }
        ],
        "status": {
            "name": "PENDING",
            "evaluated": false,
            "started": false
        },
        "fill_status": {
            "denominator": "0",
            "numerator": "0"
        },
        "start_at": "2022-03-10T05:00:50.52Z",
        "end_at": "2022-04-10T06:00:50.52Z",
        "order_hash": "0xdd62c8ff1e410075251673fdca918a1b8a26a4aaff3f558ddfe9fe88af4b30cd",
        "salt": "0x52c2669364b63b85",
        "signature": "0xb2dd0a83659d419355a6ad77ccc83c23a0d6dea6f080ecee55eb8e11cfd42848049b2649c787fa27a2caf4d340661f77d278e953fa8569d992a65883febe43ec1c",
        "protocol_data": {
            "order_type": "FULL_RESTRICTED",
            "counter": "0",
            "seaport_address": "0x7fb7da6de152597830ed16361633e362a2f59410",
            "seaport_version": "1.5",
            "zone_address": "0x63441cbfbd15dd8f5e92598e535661ac5acb808e"
        },
        "created_at": "2022-03-10T05:00:50.52Z",
        "updated_at": "2022-03-10T05:00:50.52Z"
    }
}

The live order once the balance has been confirmed by Immutable:

{
    "event_name": "imtbl_zkevm_order_updated",
    "event_id": "018b3ac9-a2df-d8d3-1a5a-2e2ac158ae59",
    "chain": "imtbl-zkevm-testnet",
    "data": {
        "type": "LISTING",
        "id": "018b3ac9-a2c3-c153-8c18-01902b663abb",
        "chain": {
            "id": "eip155:13473",
            "name": "imtbl-zkevm-testnet"
        },
        "account_address": "0xc606830d8341bc9f5f5dd7615e9313d2655b505d",
        "buy": [
            {
                "type": "NATIVE",
                "amount": "1000000"
            }
        ],
        "sell": [
            {
                "type": "ERC721",
                "contract_address": "0xfdee4926d1a7b01cc1b8d086faf0b2194c99acc8",
                "token_id": "1"
            }
        ],
        "fees": [
            {
                "type": "MAKER_ECOSYSTEM",
                "amount": "1",
                "recipient": "0xc606830d8341bc9f5f5dd7615e9313d2655b505d"
            },
            {
                "type": "PROTOCOL",
                "amount": "20000",
                "recipient": "0x9a48b1b27743d807331d06ecf0bfb15c06fdb58d"
            },
            {
                "type": "ROYALTY",
                "amount": "10000",
                "recipient": "0x9a48b1b27743d807331d06ecf0bfb15c06fdb58d"
            }
        ],
        "status": {
            "name": "ACTIVE"
        },
        "fill_status": {
            "denominator": "0",
            "numerator": "0"
        },
        "start_at": "2022-03-10T05:00:50.52Z",
        "end_at": "2022-04-10T06:00:50.52Z",
        "order_hash": "0xdd62c8ff1e410075251673fdca918a1b8a26a4aaff3f558ddfe9fe88af4b30cd",
        "salt": "0x52c2669364b63b85",
        "signature": "0xb2dd0a83659d419355a6ad77ccc83c23a0d6dea6f080ecee55eb8e11cfd42848049b2649c787fa27a2caf4d340661f77d278e953fa8569d992a65883febe43ec1c",
        "protocol_data": {
            "order_type": "FULL_RESTRICTED",
            "counter": "0",
            "seaport_address": "0x7fb7da6de152597830ed16361633e362a2f59410",
            "seaport_version": "1.5",
            "zone_address": "0x63441cbfbd15dd8f5e92598e535661ac5acb808e"
        },
        "created_at": "2022-03-10T05:00:50.52Z",
        "updated_at": "2022-03-10T05:01:50.52Z"
    }
}
Cancelled NFT order​
{
    "event_name": "imtbl_zkevm_order_updated",
    "event_id": "018b3ac9-a2df-d8d3-1a5a-2e2ac158ae59",
    "chain": "imtbl-zkevm-testnet",
    "data": {
        "type": "LISTING",
        "id": "018b3ac9-a2c3-c153-8c18-01902b663abb",
        "chain": {
            "id": "eip155:13473",
            "name": "imtbl-zkevm-testnet"
        },
        "account_address": "0xc606830d8341bc9f5f5dd7615e9313d2655b505d",
        "buy": [
            {
                "type": "NATIVE",
                "amount": "1000000"
            }
        ],
        "sell": [
            {
                "type": "ERC721",
                "contract_address": "0xfdee4926d1a7b01cc1b8d086faf0b2194c99acc8",
                "token_id": "1"
            }
        ],
        "fees": [
            {
                "type": "MAKER_ECOSYSTEM",
                "amount": "1",
                "recipient": "0xc606830d8341bc9f5f5dd7615e9313d2655b505d"
            },
            {
                "type": "PROTOCOL",
                "amount": "20000",
                "recipient": "0x9a48b1b27743d807331d06ecf0bfb15c06fdb58d"
            },
            {
                "type": "ROYALTY",
                "amount": "10000",
                "recipient": "0x9a48b1b27743d807331d06ecf0bfb15c06fdb58d"
            }
        ],
        "status": {
            "name": "CANCELLED",
            "pending": false,
            "cancellation_type": "OFF_CHAIN"
        },
        "fill_status": {
            "denominator": "0",
            "numerator": "0"
        },
        "start_at": "2022-03-10T05:00:50.52Z",
        "end_at": "2022-04-10T06:00:50.52Z",
        "order_hash": "0xdd62c8ff1e410075251673fdca918a1b8a26a4aaff3f558ddfe9fe88af4b30cd",
        "salt": "0x52c2669364b63b85",
        "signature": "0xb2dd0a83659d419355a6ad77ccc83c23a0d6dea6f080ecee55eb8e11cfd42848049b2649c787fa27a2caf4d340661f77d278e953fa8569d992a65883febe43ec1c",
        "protocol_data": {
            "order_type": "FULL_RESTRICTED",
            "counter": "0",
            "seaport_address": "0x7fb7da6de152597830ed16361633e362a2f59410",
            "seaport_version": "1.5",
            "zone_address": "0x63441cbfbd15dd8f5e92598e535661ac5acb808e"
        },
        "created_at": "2022-03-10T05:00:50.52Z",
        "updated_at": "2022-03-11T05:03:05.00Z"
    }
}
Filled NFT order​
{
    "event_name": "imtbl_zkevm_order_updated",
    "event_id": "018b3ac9-a2df-d8d3-1a5a-2e2ac158ae59",
    "chain": "imtbl-zkevm-testnet",
    "data": {
        "type": "LISTING",
        "id": "018b3ac9-a2c3-c153-8c18-01902b663abb",
        "chain": {
            "id": "eip155:13473",
            "name": "imtbl-zkevm-testnet"
        },
        "account_address": "0xc606830d8341bc9f5f5dd7615e9313d2655b505d",
        "buy": [
            {
                "type": "NATIVE",
                "amount": "1000000"
            }
        ],
        "sell": [
            {
                "type": "ERC721",
                "contract_address": "0xfdee4926d1a7b01cc1b8d086faf0b2194c99acc8",
                "token_id": "1"
            }
        ],
        "fees": [
            {
                "type": "MAKER_ECOSYSTEM",
                "amount": "1",
                "recipient": "0xc606830d8341bc9f5f5dd7615e9313d2655b505d"
            },
            {
                "type": "PROTOCOL",
                "amount": "20000",
                "recipient": "0x9a48b1b27743d807331d06ecf0bfb15c06fdb58d"
            },
            {
                "type": "ROYALTY",
                "amount": "10000",
                "recipient": "0x9a48b1b27743d807331d06ecf0bfb15c06fdb58d"
            }
        ],
        "status": {
            "name": "FILLED"
        },
        "fill_status": {
            "denominator": "1",
            "numerator": "1"
        },
        "start_at": "2022-03-10T05:00:50.52Z",
        "end_at": "2022-04-10T06:00:50.52Z",
        "order_hash": "0xdd62c8ff1e410075251673fdca918a1b8a26a4aaff3f558ddfe9fe88af4b30cd",
        "salt": "0x52c2669364b63b85",
        "signature": "0xb2dd0a83659d419355a6ad77ccc83c23a0d6dea6f080ecee55eb8e11cfd42848049b2649c787fa27a2caf4d340661f77d278e953fa8569d992a65883febe43ec1c",
        "protocol_data": {
            "order_type": "FULL_RESTRICTED",
            "counter": "0",
            "seaport_address": "0x7fb7da6de152597830ed16361633e362a2f59410",
            "seaport_version": "1.5",
            "zone_address": "0x63441cbfbd15dd8f5e92598e535661ac5acb808e"
        },
        "created_at": "2022-03-10T05:00:50.52Z",
        "updated_at": "2022-03-23T07:24:41.00Z"
    }
}

IMX Whitepaper • IMX Tokenomics • Block Explorer • Careers • Contact Us