Overview
What is the Webhooks API?
The Webhooks API lets you monitor real-time events on the Avalanche ecosystem, including the C-chain, L1s, and the Platform Chain (P/X chains). By subscribing to specific events, you can receive instant notifications for on-chain occurrences without continuously polling the network.
Key Features:
- Real-time notifications: Receive immediate updates on specified on-chain activities without polling.
- Customizable: Specify the desired event type to listen for, customizing notifications based on your individual requirements.
- **Secure: Employ shared secrets and signature-based verification to ensure that notifications originate from a trusted source.
- Broad Coverage:
- C-chain: Mainnet and testnet, covering smart contract events, NFT transfers, and wallet-to-wallet transactions.
- Platform Chain (P and X chains): Address and validator events, staking activities, and other platform-level transactions.
By supporting both the C-chain and the Platform Chain, you can monitor an even wider range of Avalanche activities.
Use cases
- NFT marketplace transactions: Get alerts for NFT minting, transfers, auctions, bids, sales, and other interactions within NFT marketplaces.
- Wallet notifications: Receive alerts when an address performs actions such as sending, receiving, swapping, or burning assets.
- DeFi activities: Receive notifications for various DeFi activities such as liquidity provisioning, yield farming, borrowing, lending, and liquidations.
- Staking rewards: Get real-time notifications when a validator stakes, receives delegation, or earns staking rewards on the P-Chain, enabling seamless monitoring of validator earnings and participation.
APIs for continuous polling vs. Webhooks for events data
The following example uses the address activity webhook topic to illustrate the difference between polling an API for wallet event data versus subscribing to a webhook topic to receive wallet events.
Continous polling
Continuous polling is a method where your application repeatedly sends requests to an API at fixed intervals to check for new data or events. Think of it like checking your mailbox every five minutes to see if new mail has arrived, whether or not anything is there.
- You want to track new transactions for a specific wallet.
- Your application calls an API every few seconds (e.g., every 5 seconds) with a query like, “Are there any new transactions for this wallet since my last check?”
- The API responds with either new transaction data or a confirmation that nothing has changed.
Downsides of continuous polling
- Inefficiency: Your app makes requests even when no new transactions occur, wasting computational resources, bandwidth, and potentially incurring higher API costs. For example, if no transactions happen for an hour, your app still sends hundreds of unnecessary requests.
- Delayed updates: Since polling happens at set intervals, there’s a potential delay in detecting events. If a transaction occurs just after a poll, your app won’t know until the next check—up to 5 seconds later in our example. This lag can be critical for time-sensitive applications, like trading or notifications.
- Scalability challenges: Monitoring one wallet might be manageable, but if you’re tracking dozens or hundreds of wallets, the number of requests multiplies quickly.
Webhook subscription
Webhooks are an event-driven alternative where your application subscribes to specific events, and the Avalanche service notifies you instantly when those events occur. It’s like signing up for a delivery alert—when the package (event) arrives, you get a text message right away, instead of checking the tracking site repeatedly.
- Your app registers a webhook specifying an endpoint (e.g.,
https://your-app.com/webhooks/transactions) and the event type (e.g.,address_activity). - When a new transaction occurs we send a POST request to your endpoint with the transaction details.
- Your app receives the data only when something happens, with no need to ask repeatedly.
Benefits of Avalanche webhooks
- Real-Time updates: Notifications arrive the moment a transaction is processed, eliminating delays inherent in polling. This is ideal for applications needing immediate responses, like alerting users or triggering automated actions.
- Efficiency: Your app doesn’t waste resources making requests when there’s no new data. Data flows only when events occur. This reduces server load, bandwidth usage, and API call quotas.
- Scalability: You can subscribe to events for multiple wallets or event types (e.g., transactions, smart contract calls) without increasing the number of requests your app makes. We handle the event detection and delivery, so your app scales effortlessly as monitoring needs grow.
Event payload structure
The Event structure always begins with the following parameters:
Parameters:
webhookId: Unique identifier for the webhook in your account.eventType: The event that caused the webhook to be triggered. In the future, there will be multiple types of events, for the time being only the address_activity event is supported. The address_activity event gets triggered whenever the specified addresses participate in a token or AVAX transaction.messageId: Unique identifier per event sent.event: Event payload. It contains details about the transaction, logs, and traces. By default logs and internal transactions are not included, if you want to include them use"includeLogs": true, and"includeInternalTxs": true.
Address Activity webhook
The address activity webhook allows you to track any interaction with an address (any address). Here is an example of this type of event: