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

Webhook Service requirements

A webhook event is considered successfully received when the webhook service responds with a 200 OK status.

In all other cases, the API will retry sending the same event with increasing timeouts between attempts. To maintain data integrity, all events are organized into a sequential chain. Therefore, until the webhook service successfully accepts a specific event, all subsequent events will be naturally blocked.

For this reason, responses other than 200 should not be used as a feedback mechanism (e.g., to indicate a mismatch between the expected and actual state of some entity). Such retries will not lead to a different outcome, other than the accumulation of pending events.

The maximum retention period for accumulated events is 7 days. After this period, the events will be lost.

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\"}}"
}