Skip to main content
PUT
/
v2
/
data
/
webhooks
/
subscriptions
/
{subscriptionId}
Update webhook subscription
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": [
    "onchain.activity.detected"
  ],
  "isEnabled": false,
  "target": {
    "url": "https://api.example.com/webhooks",
    "headers": {
      "Authorization": "Bearer token123",
      "Content-Type": "application/json"
    }
  },
  "description": "Updated subscription for token transfer events",
  "metadata": {
    "customer_id": "cust_12345",
    "order_reference": "order-67890"
  },
  "labels": {}
}
'
{
  "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.

Path Parameters

​
subscriptionId
string<uuid>
required

Unique identifier for the webhook subscription.

Pattern: ^[a-f0-9\-]{36}$

Body

application/json

Request to update an existing webhook subscription.

​
eventTypes
enum<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").

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:

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"
  }
}
​
description
string

Description of the webhook subscription.

Maximum string length: 500
Example:

"Updated 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.

Example:
{
  "customer_id": "cust_12345",
  "order_reference": "order-67890"
}
​
labels
object

Optional. Multi-label filters that trigger only when an event contains ALL of these key-value pairs. 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)
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 updated 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

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").

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.

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.

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.

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