Object Webhooks

⚠️ Beta Feature: Webhooks are currently in beta. While fully functional, some features are still being refined.

Monitor changes to specific on-chain objects on the Sui blockchain.

Overview

Object webhooks notify you when a specific object is modified, transferred, or deleted. This is ideal for tracking NFTs, shared objects like AMM pools, or any other Sui object.

Configuration

Field	Required	Description
Object ID	Yes	The object ID to monitor
Webhook URL	Yes	Your HTTPS endpoint

Example Payload

{
  "payloadVersion": 1,
  "payload": {
    "activityType": "object_change",
    "objectId": "0x5678efgh",
    "transactionDirection": "output",
    "writeKind": "mutated",
    "owner": "0x1234abcd",
    "previousOwner": "0x9876fedc",
    "txDigest": "Lm4Np8qrst",
    "checkpoint": 12345684,
    "timestamp": 1703097750000
  }
}

Payload Fields

Field	Type	Description
activityType	string	Always object_change
objectId	string	The monitored object ID
transactionDirection	input | output	Whether object was input or output of tx
writeKind	string	How the object was modified (see below)
owner	string | null	Current/new owner address
previousOwner	string | null	Previous owner (if ownership changed)
txDigest	string	Transaction digest
checkpoint	number	Checkpoint sequence number
timestamp	number	Unix timestamp in milliseconds

Write Kinds

The writeKind field indicates how the object was modified:

Write Kind	Description
created	Object was created in this transaction
mutated	Object was modified (fields changed)
deleted	Object was permanently deleted
wrapped	Object was wrapped inside another object
unwrapped	Object was unwrapped from another object
unwrapped_then_deleted	Object was unwrapped and then deleted

Transaction Direction

The transactionDirection field indicates the object's role:

• input: The object was read or consumed by the transaction
• output: The object was created or modified by the transaction

Use Cases

NFT Tracking

• Monitor ownership changes for specific NFTs
• Track when NFTs are listed/delisted on marketplaces
• Alert users when their NFTs are transferred

DeFi Protocol Monitoring

• Watch AMM pool state changes
• Monitor liquidity position objects
• Track shared object mutations

Gaming Applications

• Track character/item modifications
• Monitor game state objects
• Watch for item transfers or upgrades

Critical Object Auditing

• Monitor protocol treasury objects
• Track admin capability objects
• Audit critical shared objects

Best Practices

1. Know your object ID - Ensure you have the correct object ID before creating the webhook
2. Handle all write kinds - Different write kinds may require different handling
3. Track ownership changes - Compare owner and previousOwner to detect transfers
4. Monitor shared objects - Shared objects can be mutated by anyone, so they may change frequently

Next Steps

• Webhook Setup Guide - Endpoint requirements and signature verification
• Event Webhooks - Monitor smart contract events
• Address Webhooks - Monitor wallet activity
• Coin Webhooks - Track token balance changes