Skip to main content

​
Overview

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. To watch up to 100 wallet addresses for ERC-20 activity under a single subscription, see Multi-address subscriptions.

​
Event types

​
Onchain events

A single event type covers all onchain activity, filtered server-side by the labels on your subscription:
EventDescription
onchain.activity.detectedA smart contract event matching your subscription’s filters fired onchain

​
Wallet activity events

EventDescription
wallet.activity.detectedAn 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. 
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:
response.json
201 Created
{
  "createdAt": "2025-10-08T13:58:38.681893Z",
  "description": "USD Base Coin Transfers",
  "eventTypes": ["onchain.activity.detected"],
  "isEnabled": true,
  "labels": {
    "project": "<YOUR_CDP_PROJECT_ID>",
    "network": "base-mainnet",
    "contract_address": "0xd9aaec86b65d86f6a7b5b1b0c42ffa531710b6ca",
    "event_name": "Transfer"
  },
  "metadata": {
    "secret": "<SECRET_FOR_WEBHOOK_VERIFICATION>"
  },
  "subscriptionId": "<YOUR_SUBSCRIPTION_ID>",
  "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

LabelRequiredDescription
networkYesBlockchain network (e.g. base-mainnet, base-sepolia)
contract_addressNoSmart contract address (hex with 0x prefix)
event_nameNoEvent name from the contract ABI (e.g. Transfer, Burn)
event_signatureNoFull event signature (e.g. Transfer(address,address,uint256))
transaction_fromNoTransaction sender address
transaction_toNoTransaction recipient address
params.*NoAny indexed event parameter (e.g. params.from, params.to, params.value, params.tokenId)

​
Filter examples

Use caseLabels
Liquidity pool burnsnetwork=base-mainnet, contract_address=0xcd1f9777..., event_name=Burn
Price oracle updatesnetwork=base-mainnet, contract_address=0xbac4a942..., event_name=PriceUpdated
DeFi depositsnetwork=base-mainnet, contract_address=0x45c6e6a4..., event_name=Deposit
Outgoing wallet activitynetwork=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.
event-payload.json
{
  "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.
  • 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 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.

Multi-address subscriptions

Monitor up to 100 wallet addresses with a single subscription.

Wallet webhooks

Track transactions, signing operations, and delegation events for Server and Embedded Wallets.

Verify signatures

Validate that webhook payloads are genuinely from CDP.

Webhooks overview

All webhook surfaces and shared concepts.