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": [
        "onchain.activity.detected"
      ],
      "isEnabled": true,
      "labelKey": "event_name",
      "labelValue": "Transfer",
      "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"
      },
      "target": {
        "url": "https://api.example.com/webhooks"
      }
    }
  ],
  "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": [
        "onchain.activity.detected"
      ],
      "isEnabled": true,
      "labelKey": "event_name",
      "labelValue": "Transfer",
      "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"
      },
      "target": {
        "url": "https://api.example.com/webhooks"
      }
    }
  ],
  "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.

Show child attributes

subscriptions.createdAt

string<date-time>

required

When the subscription was created.

Example:

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

subscriptions.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"]

subscriptions.isEnabled

boolean

required

Whether the subscription is enabled.

Example:

true

subscriptions.subscriptionId

string<uuid>

required

Unique identifier for the subscription.

Example:

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

subscriptions.target

object

required

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

Show child attributes

subscriptions.target.url

string<uri>

required

The webhook URL to deliver events to.

Example:

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

subscriptions.target.headers

object

Additional headers to include in webhook requests.

Show child attributes

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

subscriptions.description

string

Description of the webhook subscription.

Example:

"Subscription for token transfer events"

subscriptions.metadata

object

Additional metadata for the subscription.

Show child attributes

subscriptions.metadata.secret

string<uuid>

Secret for webhook signature validation.

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

Example:

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

Example:

{
  "secret": "123e4567-e89b-12d3-a456-426614174000"
}

subscriptions.labelKey

string

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

Example:

"contract_address"

subscriptions.labelValue

string

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

Example:

"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"

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

subscriptions.labels.{key}

string

Example:

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

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

Use Cases

Authorizations

Query Parameters

Response