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": "Liquidity pool burn events.",
  "eventTypes": [
    "onchain.activity.detected"
  ],
  "labels": {
    "network": "base-mainnet",
    "contract_address": "0xcd1f9777571493aeacb7eae45cd30a226d3e612d",
    "event_name": "Burn"
  },
  "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",
  "updatedAt": "2025-11-13T11:30:00.000Z",
  "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.

Filtering

Onchain events can utilize multi-label filtering to only receive events that match all the specified labels.

Allows labels are:

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

For webhook types that aren’t onchain.*, labels are ignored.

Webhook Signature Verification

All webhooks include an HMAC-SHA256 signed header for security. The signature is signed with the secret that is returned in the secret field when creating a subscription.

Do not lose the secret, as you will not be able to recreate it. If you lose the secret, you will need to create a new subscription.

See the verification guide for implementation details.

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": "Liquidity pool burn events.",
  "eventTypes": [
    "onchain.activity.detected"
  ],
  "labels": {
    "network": "base-mainnet",
    "contract_address": "0xcd1f9777571493aeacb7eae45cd30a226d3e612d",
    "event_name": "Burn"
  },
  "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",
  "updatedAt": "2025-11-13T11:30:00.000Z",
  "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 webhook subscription with support for multi-label filtering.

eventTypes

enum<string>[]

required

Types of events to subscribe to. Event types follow a dot-separated format: service.resource.verb (e.g., "onchain.activity.detected", "wallet.activity.detected", "onramp.transaction.created", "acceptance.payment_session.authorization_succeeded"). The subscription will only receive events matching these types AND the label filter(s).

A webhook event type identifier following dot-separated format: <domain>.<entity>.<verb> (e.g., "onchain.activity.detected").

Example:

["onchain.activity.detected"]

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:

"Subscription for token transfer events"

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 10 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

Optional. Multi-label filters using total overlap logic. Total overlap means the subscription will only trigger when an event contains ALL the key-value pairs specified here. Additional labels on the event are allowed and will not prevent matching. Omit to receive all events for the selected event types.

Note: Currently, labels are supported for onchain webhooks only (max 20 labels per subscription).

Allowed labels for onchain.activity.detected (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)

Show child attributes

Examples:

{
  "network": "base-mainnet",
  "contract_address": "0xcd1f9777571493aeacb7eae45cd30a226d3e612d",
  "event_name": "Burn"
}

{
  "network": "base-mainnet",
  "contract_address": "0xbac4a9428ea707c51f171ed9890c3c2fa810305d",
  "event_name": "PriceUpdated"
}

{
  "network": "base-mainnet",
  "contract_address": "0x45c6e6a47a711b14d8357d5243f46704904578e3",
  "event_name": "Deposit"
}

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

enum<string>[]

required

A webhook event type identifier following dot-separated format: <domain>.<entity>.<verb> (e.g., "onchain.activity.detected").

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"
  }
}

updatedAt

string<date-time>

When the subscription was last updated.

Example:

"2025-01-16T14:00:00Z"

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