> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cdp.coinbase.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Onchain Activity Webhooks
> Subscribe to real-time notifications for onchain events like token transfers, smart contract activity, and NFT trades on Base.
Onchain activity webhooks let you subscribe to real-time HTTP notifications for smart contract events on Base — token transfers, swaps, NFT activity, liquidity pool actions, oracle updates, and any other event your contract emits. Events fire from the tip of chain with sub-second freshness.
Looking to track wallet operations (transactions, signing, delegation) instead of onchain events? See [Wallet webhooks](/webhooks/wallets). To watch up to 100 wallet addresses for ERC-20 activity under a single subscription, see [Multi-address subscriptions](/webhooks/onchain-activity/multi-address).
## Event types
### Onchain events
A single event type covers all onchain activity, filtered server-side by the labels on your subscription:
| Event | Description |
| --------------------------- | ------------------------------------------------------------------------- |
| `onchain.activity.detected` | A smart contract event matching your subscription's filters fired onchain |
### Wallet activity events
| Event | Description |
| -------------------------- | ---------------------------------------------------------------------------- |
| `wallet.activity.detected` | An EVM transaction matching your subscription's filters was sent or received |
## Creating a subscription
Use the CDP CLI to create a webhook subscription. The example below subscribes to USDC `Transfer` events on Base mainnet.
```bash lines theme={null}
cdp data webhooks subscriptions create \
description="USD Base Coin Transfers" \
'eventTypes:=["onchain.activity.detected"]' \
target.url=https://your-webhook-url.com \
target.method=POST \
labels.network=base-mainnet \
labels.contract_address=0xd9aaec86b65d86f6a7b5b1b0c42ffa531710b6ca \
labels.event_name=Transfer \
isEnabled:=true
```
Response:
```json title="response.json" theme={null}
201 Created
{
"createdAt": "2025-10-08T13:58:38.681893Z",
"description": "USD Base Coin Transfers",
"eventTypes": ["onchain.activity.detected"],
"isEnabled": true,
"labels": {
"project": "",
"network": "base-mainnet",
"contract_address": "0xd9aaec86b65d86f6a7b5b1b0c42ffa531710b6ca",
"event_name": "Transfer"
},
"metadata": {
"secret": ""
},
"subscriptionId": "",
"target": {
"url": "https://your-webhook-url.com"
}
}
```
## Label filtering
For `onchain.activity.detected` subscriptions, `labels` apply server-side with AND logic. You can include up to 20 labels per subscription.
### Allowed labels
| Label | Required | Description |
| ------------------ | -------- | ----------------------------------------------------------------------------------------------- |
| `network` | Yes | Blockchain network (e.g. `base-mainnet`, `base-sepolia`) |
| `contract_address` | No | Smart contract address (hex with `0x` prefix) |
| `event_name` | No | Event name from the contract ABI (e.g. `Transfer`, `Burn`) |
| `event_signature` | No | Full event signature (e.g. `Transfer(address,address,uint256)`) |
| `transaction_from` | No | Transaction sender address |
| `transaction_to` | No | Transaction recipient address |
| `params.*` | No | Any indexed event parameter (e.g. `params.from`, `params.to`, `params.value`, `params.tokenId`) |
### Filter examples
| Use case | Labels |
| ---------------------------- | ----------------------------------------------------------------------------------- |
| **Liquidity pool burns** | `network=base-mainnet`, `contract_address=0xcd1f9777...`, `event_name=Burn` |
| **Price oracle updates** | `network=base-mainnet`, `contract_address=0xbac4a942...`, `event_name=PriceUpdated` |
| **DeFi deposits** | `network=base-mainnet`, `contract_address=0x45c6e6a4...`, `event_name=Deposit` |
| **Outgoing wallet activity** | `network=base-mainnet`, `params.from=0xB7f5BF79...` |
## Webhook payload
Onchain activity payloads include the block context, contract identifiers, the decoded event parameters, and the surrounding transaction's `from` / `to` addresses.
```json title="event-payload.json" theme={null}
{
"block_number": 38218578,
"contract_address": "0x125E6687d4313864e53df431d5425969c15Eb2F",
"event_name": "Transfer",
"event_signature": "Transfer(address,address,uint256)",
"log_index": 755,
"network": "base-mainnet",
"parameters": {
"from": "0x0000000005f122FDDe066942195c10106d490486",
"to": "0x0000000000000000000000000000000000000000",
"value": "637064239"
},
"timestamp": "2025-11-15T17:08:24Z",
"transaction_from": "0x0000000005f122FDDe066942195c10106d490486",
"transaction_hash": "0xf1bdb4c4c48dd1c3c43b720890200f4d5a170c856b5c01ad1ab14e69ec",
"transaction_to": "0x0000000005f122FDDe066942195c10106d490486"
}
```
All `onchain.activity.detected` payloads include `block_number`, `timestamp`, `transaction_hash`, `network`, the contract identifiers, and event-specific decoded `parameters`.
## Supported networks
* Base mainnet
* Base Sepolia testnet
## Use cases
* **Stablecoin movement**: subscribe to USDC `Transfer` events and react instantly when digital dollars change hands.
* **NFT ownership tracking**: track wallet transfers on any ERC-721 contract.
* **Exchange & portfolio monitoring**: track ERC-20 activity across hundreds of user addresses with [multi-address subscriptions](/webhooks/onchain-activity/multi-address).
* **DeFi protocol activity**: monitor deposits, swaps, and oracle updates on any contract you care about.
## Best practices
Always verify the signature on incoming webhook payloads using the `secret` returned when you created the subscription. This ensures the payload is genuinely from CDP and has not been tampered with. See [Verify signatures](/webhooks/verify-signatures) for implementation details.
Subscriptions accept up to 20 labels and apply them with AND logic — push as much filtering into the subscription as possible to keep delivery volume manageable and your handler simple.
Return a `200` response as soon as the payload is received and signature-verified. Process the event asynchronously to avoid blocking delivery and to prevent retries from piling up.
CDP guarantees at-least-once delivery, so duplicate events are possible. Use the `transaction_hash` and `log_index` together as a unique key in your handler to skip events you have already processed.
## What to read next
Monitor up to 100 wallet addresses with a single subscription.
Track transactions, signing operations, and delegation events for Non-Custodial Wallets.
Validate that webhook payloads are genuinely from CDP.
All webhook surfaces and shared concepts.