Event Webhooks

⚠️ Beta Feature: Webhooks are currently in beta. While fully functional, some features are still being refined. We're actively indexing new event types - if your event type isn't available for field filtering yet, we'll add support shortly after you create your webhook.

Monitor specific Move event types emitted by smart contracts on the Sui blockchain.

Overview

Event webhooks notify you when specific Move events are emitted. This is the most common webhook type for DeFi applications, NFT platforms, and gaming applications.

Configuration

Field	Required	Description
Event Type	Yes	Full event type (e.g., 0x2::coin::CoinCreated)
Webhook URL	Yes	Your HTTPS endpoint
Sender	No	Filter to events from a specific address
Field Filters	No	Filter by specific event field values

Example Payload

{
  "payloadVersion": 1,
  "payload": {
    "id": "9abc123def:0",
    "activityType": "package_event",
    "txDigest": "9abc123def",
    "eventSequence": 0,
    "checkpoint": 12345678,
    "timestamp": 1703097600000,
    "type": "0x2::coin::CoinCreated<0x2::sui::SUI>",
    "sender": "0x1234abcd",
    "data": {
      "coin_type": "0x2::sui::SUI",
      "amount": "1000000000"
    }
  }
}

Payload Fields

Field	Type	Description
payloadVersion	number	API version for payload structure (currently 1)
payload.id	string	Unique event ID (txDigest:eventSequence)
payload.activityType	string	Always package_event
payload.txDigest	string	Transaction digest
payload.eventSequence	number	Event index within the transaction
payload.checkpoint	number	Checkpoint sequence number
payload.timestamp	number	Unix timestamp in milliseconds
payload.type	string	Full Move event type
payload.sender	string	Address that emitted the event
payload.data	object	Parsed event data (varies by event type)

Event Field Filtering

For indexed event types, you can add field filters to receive webhooks only when specific conditions are met. This reduces noise and lets you focus on the events that matter to your application.

How It Works

1. When you enter an event type, we check if it's in our event registry
2. If indexed, the event's fields and their Move types are displayed
3. You can add one filter per field with type-appropriate operators
4. All filters must match for the webhook to fire (AND logic)

Available Operators

Operators are determined by the Move type of the field:

Move Type	Operators
Numeric (u8, u16, u32, u64, u128, u256)	equals, not equals, >, >=, <, <=
String (address, vector<u8>, String)	equals, not equals, contains
Boolean (bool)	equals, not equals

Example Filters

Field	Type	Operator	Value	Use Case
amount	u64	>=	1000000000	Only amounts >= 1 SUI (9 decimals)
sender	address	equals	0x1234...	Only from specific sender
recipient	address	not equals	0x0	Exclude burns
pool_id	address	contains	cetus	Only Cetus pools

Filter Configuration

Field	Required	Description
Field Name	Yes	The event field to filter on
Operator	Yes	Comparison operator (based on field type)
Value	Yes	The value to compare against

💡 Tip: Field filters are powerful for high-volume events. Instead of receiving every swap event and filtering in your application, filter at the source to only receive swaps above a certain amount or from specific pools.

Unindexed Event Types

If your event type isn't indexed yet, you'll see an informational message when creating your webhook. You can still create the webhook - it will work normally for all matching events, but field filtering won't be available.

We're notified automatically when you use an unindexed event type and will add support shortly. Most popular event types from major protocols (Cetus, Turbos, Scallop, etc.) are already indexed.

Current Limitations

• Flat structures only: Only events with flat structures (key → singular value) are supported. Nested objects, arrays, and complex types within event fields cannot be filtered. Support for nested structures is planned for future versions.
• One filter per field: You can only add one filter condition per field. For example, you can't filter for amount > 100 AND amount < 1000 on the same field.
• AND logic only: All filters must match. OR logic between filters is not currently supported.
• Indexing delay: New event types may take some time to be indexed after first use.

Use Cases

DeFi Applications

• DEX Trading: React to swap events above a certain volume
• Lending Protocols: Monitor liquidation events for specific accounts
• Yield Farming: Track reward claims and stake changes

NFT Marketplaces

• Mint Events: Notify users when new NFTs are created
• Transfer Events: Update ownership records in real-time
• Sale Events: Process marketplace transactions instantly

Gaming Applications

• Battle Results: Process combat outcomes for specific characters
• Achievement Events: Trigger rewards when conditions are met
• Item Transfers: Update game state when high-value items move

Best Practices

1. Use field filters for high-volume events to reduce unnecessary webhook deliveries
2. Filter by sender when you only care about events from specific addresses
3. Start broad, then narrow - create a webhook without filters first to understand the event volume, then add filters as needed
4. Monitor your CU usage - each delivery costs 100 CU, so filtering saves compute units

Next Steps

• Webhook Setup Guide - Endpoint requirements and signature verification
• Address Webhooks - Monitor wallet activity
• Coin Webhooks - Track token balance changes
• Object Webhooks - Watch object mutations