Skip to main content
PUT
/
v2
/
data
/
webhooks
/
subscriptions
/
{subscriptionId}
curl --request PUT \
  --url https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions/{subscriptionId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "eventTypes": [
    "wallet.transaction.created",
    "token.transfer.completed",
    "wallet.transaction.failed"
  ],
  "isEnabled": false,
  "target": {
    "url": "https://api.example.com/webhooks",
    "headers": {
      "Authorization": "Bearer token123",
      "Content-Type": "application/json"
    }
  },
  "labelKey": "contract_address",
  "labelValue": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "description": "Updated subscription for token transfer events",
  "metadata": {
    "updated_field": "updated_value",
    "webhook_version": "v2"
  },
  "labels": {
    "env": "prod",
    "service": "api"
  }
}'
{
  "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.

Path Parameters

​
subscriptionId
string<uuid>
required

Unique identifier for the webhook subscription.

Body

application/json
  • Traditional single-label update format
  • Multi-label update format with total overlap logic

Request to update an existing webhook subscription. The update format must match the original subscription format (traditional or multi-label).

​
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",
  "wallet.transaction.failed"
]
​
isEnabled
boolean
required

Whether the subscription is enabled.

Example:

false

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

Example:

"contract_address"

​
labelValue
string
required

Label value for filtering events. Use either (labelKey + labelValue) OR labels, not both.

Example:

"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"

​
description
string

Description of the webhook subscription.

Example:

"Updated subscription for token transfer events"

​
metadata
object

Additional metadata for the subscription.

Example:
{
  "updated_field": "updated_value",
  "webhook_version": "v2"
}
​
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. Use either labels OR (labelKey + labelValue), not both.

Example:
{ "env": "prod", "service": "api" }

Response

Webhook subscription updated 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"
}