Webhook Events: Orders
The orders webhook event signals when a new order (listing) is placed. Orders are centralised through Immutable's Global Orderbook.
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:
- Backend Integration: Use your local application's backend to keep track of metadata attributes and
token_idtometadata_idmappings. These can be found by subscribing to NFT and Metadata events. - API Polling: Use the Blockchain Data API NFT endpoint using
token_idto 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"
}
}