> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cdp.coinbase.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/webhooks/overview).
## Prerequisites
Sign up at [portal.cdp.coinbase.com](https://portal.cdp.coinbase.com), then navigate to [API Keys](https://portal.cdp.coinbase.com/projects/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](https://webhook.site) gives free temporary URLs instantly.
For production, use your own HTTPS endpoint.
The [CDP CLI](/get-started/build-with-ai/cdp-for-agents) handles authentication and exposes webhook subscription endpoints as typed commands (`cdp data webhooks subscriptions create`, `list`, `update`, `delete`). For raw HTTP, use `cdp api`.
```bash theme={null}
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:
```json theme={null}
"target": {
"url": "https://your-webhook-url.com",
"method": "POST",
"headers": {
"custom-header": "value"
}
},
```
## 2. Create subscription
```bash lines theme={null}
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:
```json title="response.json" theme={null}
201 Created
{
"createdAt": "2025-10-08T13:58:38.681893Z",
"description": "USD Base Coin Transfers",
"eventTypes": [
"onchain.activity.detected"
],
"isEnabled": true,
"labels": {
"project": "",
"contract_address": "0xd9aaec86b65d86f6a7b5b1b0c42ffa531710b6ca", # USD Base Coin Contract Address
"event_name": "Transfer",
},
"metadata": {
"secret": ""
},
"subscriptionId": "",
"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
```bash theme={null}
cdp data webhooks subscriptions list
```
### View subscription details
```bash theme={null}
cdp data webhooks subscriptions get
```
### Update subscription
`update` requires all fields, even ones you aren't changing — it's a full replace:
```bash theme={null}
cdp data webhooks subscriptions update \
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
```bash theme={null}
cdp data webhooks subscriptions delete
```
### List subscription events
View delivery attempts for a subscription, including delivery status, retry count, and HTTP response details:
```bash theme={null}
cdp data webhooks subscriptions events
```
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:
```bash lines wrap theme={null}
cdp data webhooks subscriptions events \
minCreatedAt==2025-01-15T00:00:00Z \
eventTypeNames==onchain.activity.detected
```
## What to read next
* **[Wallet webhooks](/webhooks/wallets)**: Track the full transaction lifecycle, signing operations, and delegation events for API key wallets and user wallets.
* **[Multi-address subscriptions](/webhooks/onchain-activity/multi-address)**: Monitor up to 100 wallet addresses with a single subscription.
* **[Verify webhook signatures](/webhooks/verify-signatures)**: Learn how to verify webhook signatures to ensure events are coming from Coinbase.
* **[Support](/support/join-cdp-discord)**: Join our Discord for help and community support.