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_id
tometadata_id
mappings. These can be found by subscribing to NFT and Metadata events. - 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:
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"
}
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"
}
}