Use webhooks for real time messages

Webhooks are used to get real time guaranteed messages of ecosystem events such as state finalization, transfers, marketplace sales, and more from the platform.

You can use OpenAPI Swagger file below to generate webhook handler:

5KB

webhook_events.yaml

Messaging Notification Structure

After registration your webhook endpoint, it should be able to receive structures like this:

{
  "notificationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "notificationType": "ItemTypeStateUpdated",
  "notificationPayload": "{\"id\":\"a1b2c3d4-e5f6-7890-1234-56789abcdef0\",\"itemTypeId\":\"b2c3d4e5-f6a7-8901-2345-6789abcdef01\",\"ownerPlayerId\":\"c3d4e5f6-a7b8-9012-3456-789abcdef012\",\"tokenId\":12345,\"state\":\"active\",\"metadataUrl\":\"http://example.com/metadata/item-001\",\"metadata\":{\"key\":\"value\"}}"
}

Fields Description:

• NotificationId - a unique identifier for each notification.

• NotificationType - a string indicating the type of the event. This value helps determine how to interpret the payload.

  • Can be one of:

    • ItemTypeStateUpdated

    • ItemUpdateError

    • ItemStateUpdated

    • ItemMetadataUpdated

    • PurchaseCompleted

    • SellCompleted

    • QuickTradeCreated

    • QuickTradeReserved

    • QuickTradeCompleted

• NotificationPayload - a JSON-marshalled string containing the payload data.

The NotificationType field indicates whether the NotificationPayload should be unmarshalled into corresponding structure:

• Item (for ItemTypeStateUpdated, ItemUpdateError, ItemStateUpdated)

• ItemType (for ItemMetadataUpdated)

• PurchaseCompleted

• SellCompleted

• QuickTradeCreated

• QuickTradeReserved

• QuickTradeCompleted

Example Responses with Random Data

Below are two example responses using the ServerMessagingNotification struct with random data.

Example 1: Item Event Notification

In this example, the payload is marshalled from an Item object.

{
  "notificationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "notificationType": "ItemTypeStateUpdated",
  "notificationPayload": "{\"id\":\"a1b2c3d4-e5f6-7890-1234-56789abcdef0\",\"itemTypeId\":\"b2c3d4e5-f6a7-8901-2345-6789abcdef01\",\"ownerPlayerId\":\"c3d4e5f6-a7b8-9012-3456-789abcdef012\",\"tokenId\":12345,\"state\":\"active\",\"metadataUrl\":\"http://example.com/metadata/item-001\",\"metadata\":{\"key\":\"value\"}}"
}

Example 2: Item Type Event Notification

Here, the payload is marshalled from an ItemType object.

{
  "notificationId": "7f8e9d10-1112-1314-1516-171819202122",
  "notificationType": "ItemMetadataUpdated",
  "notificationPayload": "{\"id\":\"e5f6a7b8-c9d0-1234-5678-9abcdef01234\",\"state\":\"updated\",\"collectionName\":\"Example Collection\",\"maxSupply\":1000,\"issuedSupply\":250,\"circulatingSupply\":200,\"mintMode\":\"automatic\",\"defaultMetadata\":{\"key\":\"default\"}}"
}