curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "All transfer status change events.",
  "eventTypes": [
    "payments.transfers.quoted",
    "payments.transfers.processing",
    "payments.transfers.completed",
    "payments.transfers.failed"
  ],
  "labels": {},
  "target": {
    "url": "https://api.example.com/webhooks"
  },
  "isEnabled": true
}
'

{
  "subscriptionId": "123e4567-e89b-12d3-a456-426614174000",
  "eventTypes": [
    "onchain.activity.detected"
  ],
  "isEnabled": true,
  "labels": {
    "contract_address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "event_name": "Transfer",
    "network": "base-mainnet",
    "transaction_to": "0xf5042e6ffac5a625d4e7848e0b01373d8eb9e222"
  },
  "description": "USDC Transfer events to specific address.",
  "createdAt": "2025-11-12T09:19:52.051Z",
  "metadata": {
    "secret": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "secret": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "target": {
    "url": "https://api.example.com/webhooks"
  }
}

Webhooks

Create webhook subscription

Subscribe to real-time events across CDP products using flexible filtering.

Event Types

Onchain Events - Monitor Base mainnet with microsecond precision:

onchain.activity.detected - Smart contract events, transfers, swaps, NFT activity
Requires labels for filtering (e.g., contract_address, event_name)

Onramp/Offramp Events - Transaction lifecycle notifications:

onramp.transaction.created, onramp.transaction.updated
onramp.transaction.success, onramp.transaction.failed
offramp.transaction.created, offramp.transaction.updated
offramp.transaction.success, offramp.transaction.failed
No labels required - maximum simplicity for transaction monitoring

Payments Transfers Events - Transfer lifecycle notifications:

payments.transfers.quoted
payments.transfers.processing
payments.transfers.completed
payments.transfers.failed
No labels required - enable the transfers webhook to monitor status transitions

Wallet Events - Wallet activity notifications:

wallet.activity.detected

Webhook Signature Verification

All webhooks include cryptographic signatures for security. The signature secret is returned in secret field when creating a subscription.

Note: Webhooks are in beta and this interface is subject to change.

See the verification guide for implementation details.

Onchain Label Filtering

For onchain.activity.detected events, use labels for precise filtering with AND logic (max 20 labels per webhook).

Allowed labels (all in snake_case format):

network (required) - Blockchain network
contract_address - Smart contract address
event_name - Event name (e.g., “Transfer”, “Burn”)
event_signature - Event signature hash
transaction_from - Transaction sender address
transaction_to - Transaction recipient address
params.* - Any event parameter (e.g., params.from, params.to, params.sender, params.tokenId)

Examples:

Liquidity Pool Monitor: {"network": "base-mainnet", "contract_address": "0xcd1f9777571493aeacb7eae45cd30a226d3e612d", "event_name": "Burn"}
Price Oracle Tracker: {"network": "base-mainnet", "contract_address": "0xbac4a9428ea707c51f171ed9890c3c2fa810305d", "event_name": "PriceUpdated"}
DeFi Protocol Activity: {"network": "base-mainnet", "contract_address": "0x45c6e6a47a711b14d8357d5243f46704904578e3", "event_name": "Deposit"}

POST

data

webhooks

subscriptions

curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "All transfer status change events.",
  "eventTypes": [
    "payments.transfers.quoted",
    "payments.transfers.processing",
    "payments.transfers.completed",
    "payments.transfers.failed"
  ],
  "labels": {},
  "target": {
    "url": "https://api.example.com/webhooks"
  },
  "isEnabled": true
}
'

{
  "subscriptionId": "123e4567-e89b-12d3-a456-426614174000",
  "eventTypes": [
    "onchain.activity.detected"
  ],
  "isEnabled": true,
  "labels": {
    "contract_address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "event_name": "Transfer",
    "network": "base-mainnet",
    "transaction_to": "0xf5042e6ffac5a625d4e7848e0b01373d8eb9e222"
  },
  "description": "USDC Transfer events to specific address.",
  "createdAt": "2025-11-12T09:19:52.051Z",
  "metadata": {
    "secret": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "secret": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "target": {
    "url": "https://api.example.com/webhooks"
  }
}

Authorizations

Authorization

string

header

required

A JWT signed using your CDP API Key Secret, encoded in base64. Refer to the Generate Bearer Token section of our Authentication docs for information on how to generate your Bearer Token.

Body

application/json

Request to create a new transfer webhook subscription.

eventTypes

string[]

required

Types of transfer events to subscribe to. Valid values are: payments.transfers.quoted, payments.transfers.processing, payments.transfers.completed, payments.transfers.failed.

Example:

["payments.transfers.completed"]

isEnabled

boolean

required

Whether the subscription is enabled.

Example:

true

target

object

required

Target configuration for webhook delivery. Specifies the destination URL and any custom headers to include in webhook requests.

Show child attributes

Example:

{
  "url": "https://api.example.com/webhooks",
  "headers": {
    "Authorization": "Bearer token123",
    "Content-Type": "application/json"
  }
}

description

string

Description of the webhook subscription.

Maximum string length: 500

Example:

"Transfer status change notifications"

metadata

object

Optional metadata as key-value pairs. Use this to store additional structured information on a resource, such as customer IDs, order references, or any application-specific data. Up to 50 key/value pairs may be provided. Keys and values are both strings. Keys must be ≤ 40 characters; values must be ≤ 500 characters.

Show child attributes

Example:

{
  "customer_id": "cust_12345",
  "order_reference": "order-67890"
}

labels

object

Labels are not supported for transfer webhooks.

Show child attributes

Example:

{}

Response

Webhook subscription created successfully.

Response containing webhook subscription details.

createdAt

string<date-time>

required

When the subscription was created.

Example:

"2025-01-15T10:30:00Z"

eventTypes

string[]

required

Types of events to subscribe to. Event types follow a three-part dot-separated format: service.resource.verb (e.g., "onchain.activity.detected", "wallet.activity.detected", "onramp.transaction.created").

Example:

["onchain.activity.detected"]

isEnabled

boolean

required

Whether the subscription is enabled.

Example:

true

secret

string<uuid>

required

Secret for webhook signature validation.

Example:

"123e4567-e89b-12d3-a456-426614174000"

subscriptionId

string<uuid>

required

Unique identifier for the subscription.

Example:

"123e4567-e89b-12d3-a456-426614174000"

target

object

required

Target configuration for webhook delivery. Specifies the destination URL and any custom headers to include in webhook requests.

Show child attributes

Example:

{
  "url": "https://api.example.com/webhooks",
  "headers": {
    "Authorization": "Bearer token123",
    "Content-Type": "application/json"
  }
}

description

string

Description of the webhook subscription.

Maximum string length: 500

Example:

"Subscription for token transfer events"

metadata

object

Additional metadata for the subscription.

Show child attributes

Example:

{
  "customer_id": "cust_12345",
  "order_reference": "order-67890",
  "secret": "123e4567-e89b-12d3-a456-426614174000"
}

labels

object

Multi-label filters using total overlap logic. Total overlap means the subscription only triggers when events contain ALL these key-value pairs. Present when subscription uses multi-label format.

Show child attributes

Example:

{
  "env": "dev",
  "team": "payments",
  "contract_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
}

List webhook subscriptions

Update webhook subscription

⌘I

CDP API V2

REST API

Create webhook subscription

Event Types

Webhook Signature Verification

Onchain Label Filtering

Authorizations

Body

Response