Skip to main content

​
Overview

Get started with CDP webhooks in just a few steps. This guide walks through creating a subscription that monitors USDC transfers on Base. Once you have the basic flow working, swap in any of the other event domains.

​
Prerequisites

Sign up at portal.cdp.coinbase.com, then navigate to API Keys and select Create API key under the Secret API Keys tab.
  1. Enter an API key nickname (restrictions are optional)
  2. Click Create
  3. Secure your API Key ID and Secret in a safe location
You’ll need an HTTPS URL to receive webhook events. For quick testing, webhook.site gives free temporary URLs instantly.For production, use your own HTTPS endpoint.
The CDP CLI handles authentication and exposes webhook subscription endpoints as typed commands (cdp data webhooks subscriptions create, list, update, delete). For raw HTTP, use cdp api.
npm install -g @coinbase/cdp-cli
cdp env live --key-file ./cdp_api_key.json
cdp data webhooks subscriptions list

​
1. Review the configuration

The contract_address used in the example below is the USD Base Coin contract.

​
Configuration fields

Below is a list of all payload information that can be provided when creating a webhook subscription:
FieldDescriptionRequiredNotes
target.urlYour webhook endpoint URLYesMust be a valid HTTPS URL
labels.contract_addressSmart contract address to monitorYesHex address with 0x prefix
labels.event_nameSmart contract event nameYes* (this OR event_signature)Event name from ABI (e.g., Transfer)
labels.event_signatureSmart contract event signatureYes* (this OR event_name)Full signature (e.g., Transfer(address,address,uint256))
eventTypesArray of event typesNoUse ["onchain.activity.detected"] if provided
isEnabledEnable/disable webhookNoDefaults to true
target.headersCustom HTTP headersNoObject with header key-value pairs
labels.transaction_fromTransaction source addressNo
labels.transaction_toTransaction destination addressNo
labels.networkNetwork name (e.g. base-mainnet or base-sepolia)NoDefaults to base-mainnet
labels.params.[any_param]Any smart contract parameterNoAdd any parameter from the contract event for hyper-granular filtering (e.g., params.from, params.to, params.value)

​
Custom headers

You can also set a headers object in target if your URL requires specific headers: 
"target": {
    "url": "https://your-webhook-url.com",
    "method": "POST",
    "headers": {
      "custom-header": "value"
    }
},

​
2. Create subscription

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.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>",
    "contract_address": "0xd9aaec86b65d86f6a7b5b1b0c42ffa531710b6ca", # USD Base Coin Contract Address
    "event_name": "Transfer",
  },
  "metadata": {
    "secret": "<SECRET_FOR_WEBHOOK_VERIFICATION>"
  },
  "subscriptionId": "<YOUR_SUBSCRIPTION_ID>",
  "target": {
    "url": "https://your-webhook-url.com"
  }
}

​
Manage subscriptions

Use the subscriptionId from the response to view, update, or delete the subscription.

​
List all subscriptions

cdp data webhooks subscriptions list

​
View subscription details

cdp data webhooks subscriptions get <SUBSCRIPTION_ID>

​
Update subscription

update requires all fields, even ones you aren’t changing — it’s a full replace: 
cdp data webhooks subscriptions update <SUBSCRIPTION_ID> \
  description="Updated: USD Base Coin Transfers" \
  'eventTypes:=["onchain.activity.detected"]' \
  target.url=https://your-webhook-url.com \
  target.method=POST \
  labels.contract_address=0xd9aaec86b65d86f6a7b5b1b0c42ffa531710b6ca \
  labels.event_name=Transfer \
  isEnabled:=true
Run cdp data webhooks subscriptions update --help to see all available fields.

​
Delete subscription

cdp data webhooks subscriptions delete <SUBSCRIPTION_ID>

​
List subscription events

View delivery attempts for a subscription, including delivery status, retry count, and HTTP response details: 
cdp data webhooks subscriptions events <SUBSCRIPTION_ID>
You can narrow results with the following optional query parameters (use == for query params):
ParameterDescription
eventIdFilter by a specific event ID
minCreatedAtOnly include events created at or after this timestamp (RFC 3339, e.g. 2025-01-15T00:00:00Z)
maxCreatedAtOnly include events created at or before this timestamp (RFC 3339)
eventTypeNamesFilter by event type names, comma-separated (e.g. onchain.activity.detected)
Results are limited to the 50 most recent events, returned newest first. Example with filters: 
cdp data webhooks subscriptions events <SUBSCRIPTION_ID> \
  minCreatedAt==2025-01-15T00:00:00Z \
  eventTypeNames==onchain.activity.detected
  • Wallet webhooks: Track the full transaction lifecycle, signing operations, and delegation events for Server and Embedded Wallets.
  • Multi-address subscriptions: Monitor up to 100 wallet addresses with a single subscription.
  • Verify webhook signatures: Learn how to verify webhook signatures to ensure events are coming from Coinbase.
  • Support: Join our Discord for help and community support.