Skip to main content

​
Overview

Get started with Onchain Webhooks in just a few steps. This guide will help you create a webhook subscription via our REST endpoints and receive the events at a target destination.

​
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.
Install cdpcurl to make authenticated requests to CDP APIs:
# With Homebrew
brew tap coinbase/cdpcurl && brew install cdpcurl

# Or with Go
go install github.com/coinbase/cdpcurl@latest

​
1. Construct subscription payload

Create a JSON payload to be used with cdpcurl in the next step:
subscription.json
{
  "description": "USD Base Coin Transfers",
  "eventTypes": [
    "onchain.activity.detected",
  ],
  "target": {
    "url": "https://your-webhook-url.com",
    "method": "POST"
  },
  "labels": {
    "contract_address": "0xd9aaec86b65d86f6a7b5b1b0c42ffa531710b6ca", # USD Base Coin Contract Address
    "event_name": "Transfer",
  },
  "isEnabled": true
}

​
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:
custom-headers.json
"target": {
    "url": "https://your-webhook-url.com",
    "method": "POST",
    "headers": {
      "custom-header": "value"
    }
},

​
2. Create subscription

Using the configuration you created in the previous step, create the webhook subscription using cdpcurl: 
cdpcurl -X POST \
  -i "YOUR_API_KEY_ID" \
  -s "YOUR_API_KEY_SECRET" \
  "https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions" \
  -d '{
  "description": "USD Base Coin Transfers",
  "eventTypes": [
    "onchain.activity.detected",
  ],
  "target": {
    "url": "https://your-webhook-url.com",
    "method": "POST"
  },
  "labels": {
    "contract_address": "0xd9aaec86b65d86f6a7b5b1b0c42ffa531710b6ca", # USD Base Coin Contract Address
    "event_name": "Transfer",
  },
  "isEnabled": true
}'
You should see a response similar to the following:
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"
  }
}

​
Additional endpoints

See the following examples to view, update, or delete the subscription using the subscriptionId from the response.

​
List all subscriptions

cdpcurl -X GET \
  -i "YOUR_API_KEY_ID" \
  -s "YOUR_API_KEY_SECRET" \
  "https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions"

​
View subscription details

cdpcurl -X GET \
  -i "YOUR_API_KEY_ID" \
  -s "YOUR_API_KEY_SECRET" \
  "https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions/<SUBSCRIPTION_ID>"

​
Update subscription

cdpcurl -X PUT \
  -i "YOUR_API_KEY_ID" \
  -s "YOUR_API_KEY_SECRET" \
  "https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions/<SUBSCRIPTION_ID>" \
  -d '{
    "description": "Updated: USD Base Coin Transfers",
    "eventTypes": [
    "onchain.activity.detected",
    ],
    "target": {
      "url": "https://your-webhook-url.com",
      "method": "POST"
    },
    "labels": {},
    "isEnabled": true
  }'

​
Delete subscription

cdpcurl -X DELETE \
  -i "YOUR_API_KEY_ID" \
  -s "YOUR_API_KEY_SECRET" \
  "https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions/<SUBSCRIPTION_ID>"