Accounts5

Customers6

Deposit Destinations3

Disbursements3

End User Account Management9

End User Accounts26

EVM Accounts15

EVM Smart Accounts12

EVM Swaps2

EVM Token Balances1

Faucets2

Mandates12

Onchain Data2

Onramp7

Payment Methods2

Payment Sessions21

Policy Engine5

Solana Accounts11

Solana Token Balances1

SQL API3

Transfers5

Webhooks6

x402 Facilitator10

Webhooks

Customers2

Disbursements3

Health5

Mandates8

Onchain Data3

Onramp8

Payment Sessions14

Transfers7

Wallet Webhooks12

Webhooks

Create webhook subscription

Changed on Oct 6, 2026

Subscribe to real-time events across CDP products. A webhook subscription provides a targetURL and other relevant endpoint configuration to enable receiving webhooks when events occur.

An entity can have up to 100 webhook subscriptions. Once this limit is reached, new webhook subscription creation requests return a 400 error with errorType: subscription_limit_exceeded.

Webhook Signature Verification

All webhooks include an HMAC-SHA256 signed header for security. The signature is signed with the secret that is returned in the secret field when creating a subscription.

Do not lose the secret, as you will not be able to recreate it. If you lose the secret, you will need to create a new subscription.

See the verification guide for implementation details.

post/v2/data/webhooks/subscriptions

Request

Base URL: https://api.cdp.coinbase.com/platform
URL: https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions
Auth: HTTP bearer

Request body

descriptionstring

A human-readable description of the webhook subscription. Must be at most 100 characters.

eventTypesEventType[] 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"). The subscription will only receive events matching these types AND the label filter(s).

isEnabledboolean required

Whether the subscription is enabled.

metadataWebhookMetadata

Optional subscription metadata. Up to 10 key/value pairs may be provided. Keys and values must each contain between 1 and 50 characters.

labelsWebhookRequestLabels

String-valued filters supplied when creating or updating a webhook subscription. The subscription's eventTypes determine whether labels are required and which label keys are accepted. A subscription accepts at most 20 client-supplied labels.

Label Behavior

An event must match ALL labels to fire to your subscription targetURL. When multiple labels are supplied, the event must match ALL labels to fire to your subscription targetURL.

Example request

{
  "description": "Subscription for token transfer events",
  "eventTypes": [
    "onchain.activity.detected"
  ],
  "isEnabled": true,
  "target": {
    "url": "https://api.example.com/webhooks",
    "headers": {
      "Authorization": "Bearer token123",
      "Content-Type": "application/json"
    }
  },
  "metadata": {
    "foo": "bar",
    "baz": "qux"
  },
  "labels": {
    "network": "base-mainnet",
    "contract_address": "0xcd1f9777571493aeacb7eae45cd30a226d3e612d",
    "event_name": "Burn"
  }
}

Response

Webhook subscription created successfully.

createdAtstring date-time required

When the subscription was created.

updatedAtstring date-time

When the subscription was last updated.

descriptionstring

A human-readable description of the webhook subscription. Must be at most 100 characters.

eventTypesEventType[] required

isEnabledboolean required

Whether the subscription is enabled.

secretstring uuid required

Secret for webhook signature validation.

subscriptionIdstring uuid required

Unique identifier for the subscription.

labelsWebhookResponseLabels

Effective filters stored on the webhook subscription. The response includes client-supplied labels plus labels defaulted or injected by the server.

onchain.activity.detected, wallet.activity.detected, and wallet.activity.multi include network. It defaults to base-mainnet when omitted from the request.
wallet.activity.multi includes the requested comma-separated wallet_addresses.
health.* includes the requested service.
Project-scoped events include the authenticated project.
Entity-scoped events include the authenticated entity.
User-scoped events include the authenticated user_uuid and a sandbox value.

Example response

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

Changes

Oct 6, 2026156440e9f8df Revision changes
- warning
  added the new acceptance.mandate.approval_failed enum value to the / response property for the response status
- warning
  added the new acceptance.mandate.approval_initiated enum value to the / response property for the response status
- warning
  added the new acceptance.mandate.approval_succeeded enum value to the / response property for the response status
- warning
  added the new acceptance.mandate.canceled enum value to the / response property for the response status
- warning
  added the new acceptance.mandate.created enum value to the / response property for the response status
- warning
  added the new acceptance.mandate.revocation_failed enum value to the / response property for the response status
- warning
  added the new acceptance.mandate.revocation_initiated enum value to the / response property for the response status
- warning
  added the new acceptance.mandate.revocation_succeeded enum value to the / response property for the response status
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
- info
  added the new acceptance.mandate.approval_failed enum value to the request property /
- info
  added the new acceptance.mandate.approval_initiated enum value to the request property /
- info
  added the new acceptance.mandate.approval_succeeded enum value to the request property /
- info
  added the new acceptance.mandate.canceled enum value to the request property /
- info
  added the new acceptance.mandate.created enum value to the request property /
- info
  added the new acceptance.mandate.revocation_failed enum value to the request property /
- info
  added the new acceptance.mandate.revocation_initiated enum value to the request property /
- info
  added the new acceptance.mandate.revocation_succeeded enum value to the request property /
Sep 25, 2026229ed860a74b Revision changes
- breaking
  added 'else' subschema to the request body
- breaking
  added 'if' subschema to the request body
- breaking
  added 'then' subschema to the request body
- breaking
  the / request property's maxLength was decreased to 50
- breaking
  the / request property's minLength was increased from 0 to 1
- breaking
  added 'propertyNames' constraint to the request property
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status
- info
  added 'else' subschema to the response body for the status
- info
  added 'if' subschema to the response body for the status
- info
  added 'then' subschema to the response body for the status

Operation history (17 revisions)