Webhooks Quickstart

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

A Secret API Key

Sign up at portal.cdp.coinbase.com, then navigate to API Keys and select Create API key under the Secret API Keys tab.

Enter an API key nickname (restrictions are optional)
Click Create
Secure your API Key ID and Secret in a safe location

A webhook URL

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.

CDP CLI

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:

Field	Description	Required	Notes
`target.url`	Your webhook endpoint URL	Yes	Must be a valid HTTPS URL
`labels.contract_address`	Smart contract address to monitor	Yes	Hex address with `0x` prefix
`labels.event_name`	Smart contract event name	Yes* (this OR `event_signature`)	Event name from ABI (e.g., `Transfer`)
`labels.event_signature`	Smart contract event signature	Yes* (this OR `event_name`)	Full signature (e.g., `Transfer(address,address,uint256)`)
`eventTypes`	Array of event types	No	Use `["onchain.activity.detected"]` if provided
`isEnabled`	Enable/disable webhook	No	Defaults to `true`
`target.headers`	Custom HTTP headers	No	Object with header key-value pairs
`labels.transaction_from`	Transaction source address	No
`labels.transaction_to`	Transaction destination address	No
`labels.network`	Network name (e.g. `base-mainnet` or `base-sepolia`)	No	Defaults to `base-mainnet`
`labels.params.[any_param]`	Any smart contract parameter	No	Add 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):

Parameter	Description
`eventId`	Filter by a specific event ID
`minCreatedAt`	Only include events created at or after this timestamp (RFC 3339, e.g. `2025-01-15T00:00:00Z`)
`maxCreatedAt`	Only include events created at or before this timestamp (RFC 3339)
`eventTypeNames`	Filter 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

GET STARTED

WALLETS

PAYMENTS

STABLECOINS

TRADING

ONCHAIN TOOLS

CUSTOMERS

WEBHOOKS

CONSUMER APIS

BUSINESS APIS

INSTITUTIONAL APIS

Overview

Prerequisites

1. Review the configuration

Configuration fields

Custom headers

2. Create subscription

Manage subscriptions

List all subscriptions

View subscription details

Update subscription

Delete subscription

List subscription events

What to read next

​Overview

​Prerequisites

​1. Review the configuration

​Configuration fields

​Custom headers

​2. Create subscription

​Manage subscriptions

​List all subscriptions

​View subscription details

​Update subscription

​Delete subscription

​List subscription events

​What to read next

Overview

Prerequisites

1. Review the configuration

Configuration fields

Custom headers

2. Create subscription

Manage subscriptions

List all subscriptions

View subscription details

Update subscription

Delete subscription

List subscription events

What to read next