List webhook subscriptions

curl --request GET \
  --url https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions \
  --header 'Authorization: Bearer <token>'

{
  "subscriptions": [
    {
      "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"
        }
      }
    }
  ],
  "nextPageToken": "eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ=="
}

GET

data

webhooks

subscriptions

List webhook subscriptions

curl --request GET \
  --url https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions \
  --header 'Authorization: Bearer <token>'

{
  "subscriptions": [
    {
      "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"
        }
      }
    }
  ],
  "nextPageToken": "eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ=="
}

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.

Query Parameters

pageSize

integer

default:20

The number of subscriptions to return per page.

Required range: 1 <= x <= 100

pageToken

string

The token for the next page of subscriptions, if any.

Response

Webhook subscriptions retrieved successfully.

Response containing a list of webhook subscriptions.

subscriptions

object[]

required

The list of webhook subscriptions.

Response containing webhook subscription details.

Show child attributes

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.

Show child attributes

target.url

string<uri>

required

The webhook URL to deliver events to.

Example:

"https://api.example.com/webhooks"

target.headers

object

Additional headers to include in webhook requests.

Show child attributes

target.headers.{key}

string

Example:

{
  "Authorization": "Bearer token123",
  "Content-Type": "application/json"
}

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.

Show child attributes

metadata.secret

string<uuid>

Secret for webhook signature validation.

Example:

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

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.

Show child attributes

labels.{key}

string

Example:

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

Example:

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

nextPageToken

string

The token for the next page of items, if any.

Example:

"eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ=="

Get webhook subscription details

Create webhook subscription

⌘I

CDP PAYMENTS API

REST API

List webhook subscriptions

Authorizations

Query Parameters

Response