Skip to main content
POST
/
v2
/
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 '{
  "eventTypes": [
    "wallet.transaction.created",
    "token.transfer.completed"
  ],
  "isEnabled": true,
  "target": {
    "url": "https://api.example.com/webhooks",
    "headers": {
      "Authorization": "Bearer token123",
      "Content-Type": "application/json"
    }
  },
  "labelKey": "contract_address",
  "labelValue": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "description": "Subscription for token transfer events",
  "metadata": {
    "custom_field": "custom_value",
    "webhook_version": "v1"
  },
  "labels": {
    "env": "dev",
    "team": "payments",
    "contract_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  }
}'
{
  "subscriptionId": "123e4567-e89b-12d3-a456-426614174000",
  "eventTypes": [
    "wallet.transaction.created",
    "token.transfer.completed"
  ],
  "isEnabled": true,
  "labelKey": "contract_address",
  "labelValue": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "description": "Subscription for token transfer events.",
  "createdAt": "2025-01-15T10:30:00Z",
  "metadata": {
    "secret": "123e4567-e89b-12d3-a456-426614174000"
  },
  "target": {
    "url": "https://api.example.com/webhooks",
    "headers": {
      "Authorization": "Bearer token123"
    }
  }
}

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
  • Traditional single-label format
  • Multi-label format with total overlap logic

Request to create a new webhook subscription with support for both traditional single-label and multi-label filtering formats.

​
eventTypes
string[]
required

Types of events to subscribe to. Event types follow a three-part dot-separated format: service.resource.verb (e.g., "wallet.transaction.created", "token.transfer.completed"). The subscription will only receive events matching these types AND the label filter(s).

Example:
[
  "wallet.transaction.created",
  "token.transfer.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.

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

Label key for filtering events. Each subscription filters on exactly one (labelKey, labelValue) pair in addition to the event types. Only events matching both the event types AND this label filter will be delivered. NOTE: Use either (labelKey + labelValue) OR labels, not both.

Example:

"contract_address"

​
labelValue
string
required

Label value for filtering events. Must correspond to the labelKey (e.g., contract address for contract_address key). Only events with this exact label value will be delivered. NOTE: Use either (labelKey + labelValue) OR labels, not both.

Example:

"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"

​
description
string

Description of the webhook subscription.

Example:

"Subscription for token transfer events"

​
metadata
object

Additional metadata for the subscription.

Example:
{
  "custom_field": "custom_value",
  "webhook_version": "v1"
}
​
labels
object

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. NOTE: Use either labels OR (labelKey + labelValue), not both.

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

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., "wallet.transaction.created", "token.transfer.completed").

Example:
[
  "wallet.transaction.created",
  "token.transfer.completed"
]
​
isEnabled
boolean
required

Whether the subscription is enabled.

Example:

true

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

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

Description of the webhook subscription.

Example:

"Subscription for token transfer events"

​
metadata
object

Additional metadata for the subscription.

Example:
{
  "secret": "123e4567-e89b-12d3-a456-426614174000"
}
​
labelKey
string

Label key for filtering events. Present when subscription uses traditional single-label format.

Example:

"contract_address"

​
labelValue
string

Label value for filtering events. Present when subscription uses traditional single-label format.

Example:

"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"

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

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