Webhooks Quickstart

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

1. Create 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.

   1. Enter an API key nickname (restrictions are optional)
   2. Click Create
   3. Secure your API Key ID and Secret in a safe location
2. Install cdpcurl

   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
   

3. Get a webhook URL

   You’ll need an HTTPS URL to receive webhook events.

   Tip: Setting up your URL

   Easiest for testing: You can use webhook.site to get a free temporary URL instantly where you can view payloads and test with up to 100 events before rate limits apply.

1. Construct subscription payload

Create a JSON payload to be used with cdpcurl in the next step:

subscription.json

{
  "description": "KyberSwap Bot USDC Transfers",
  "eventTypes": [
    "onchain.activity.detected",
  ],
  "target": {
    "url": "https://your-webhook-url.com",
    "method": "POST"
  },
  "labels": {
    "contract_address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", # USDC Contract Address
    "event_name": "Transfer",
    "transaction_from": "0xf20d2e37514195ebedb0bc735ba6090ce103d38c" # Optional: Filter to only receive transfers from this specific address (KyberSwap Bot Wallet)
  },
  "isEnabled": true
}

Configuration fields

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.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:

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": "KyberSwap Bot USDC Transfers",
  "eventTypes": [
    "onchain.activity.detected",
  ],
  "target": {
    "url": "https://your-webhook-url.com",
    "method": "POST"
  },
  "labels": {
    "contract_address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", # USDC Contract Address
    "event_name": "Transfer",
    "transaction_from": "0xf20d2e37514195ebedb0bc735ba6090ce103d38c" # Optional: Filter to only receive transfers that originate from a KyberSwap Bot Wallet
  },
  "isEnabled": true
}'

You should see a response similar to the following:

response.json

201 Created
{
  "createdAt": "2025-10-08T13:58:38.681893Z",
  "description": "KyberSwap Bot USDC Transfers",
  "eventTypes": [
    "onchain.activity.detected"
  ],
  "isEnabled": true,
  "labels": {
    "project": "<YOUR_CDP_PROJECT_ID>",
    "contract_address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "event_name": "Transfer",
    "transaction_from": "0xf20d2e37514195ebedb0bc735ba6090ce103d38c"
  },
  "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: KyberSwap Bot USDC 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>"

What to read next

• Verify webhook signatures: Learn how to verify webhook signatures to ensure events are coming from Coinbase
• REST API Reference: View the complete webhook API documentation
• Support: Join our Discord for help and community support