Create webhook subscription

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.

Body

application/json

Request to create a new webhook subscription with support for multi-label filtering.

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

A webhook event type identifier following dot-separated format: <domain>.<entity>.<verb> (e.g., "onchain.activity.detected").

Available options:

onchain.activity.detected,

wallet.activity.detected,

wallet.activity.multi,

wallet.transaction.created,

wallet.transaction.signed,

wallet.transaction.broadcast,

wallet.transaction.replaced,

wallet.transaction.pending,

wallet.transaction.confirmed,

wallet.transaction.failed,

wallet.delegation.created,

wallet.delegation.revoked,

wallet.typed_data.signed,

wallet.message.signed,

wallet.hash.signed,

payments.transfers.quoted,

payments.transfers.processing,

payments.transfers.completed,

payments.transfers.failed,

payments.transfers.expired,

payments.transfers.travel_rule_incomplete,

payments.transfers.travel_rule_completed,

onramp.transaction.created,

onramp.transaction.updated,

onramp.transaction.success,

onramp.transaction.failed,

offramp.transaction.created,

offramp.transaction.updated,

offramp.transaction.success,

offramp.transaction.failed,

acceptance.payment_session.created,

acceptance.payment_session.canceled,

acceptance.payment_session.authorization_pending,

acceptance.payment_session.authorization_succeeded,

acceptance.payment_session.authorization_failed,

acceptance.payment_session.capture_pending,

acceptance.payment_session.capture_succeeded,

acceptance.payment_session.capture_failed,

acceptance.payment_session.refund_pending,

acceptance.payment_session.refund_succeeded,

acceptance.payment_session.refund_failed,

acceptance.payment_session.void_pending,

acceptance.payment_session.void_succeeded,

acceptance.payment_session.void_failed,

acceptance.disbursement.pending,

acceptance.disbursement.succeeded,

acceptance.disbursement.failed,

health.status.updated,

health.maintenance.scheduled,

health.maintenance.started,

health.maintenance.completed,

health.maintenance.canceled,

customers.capability.changed,

customers.customer.deleted

Example:

["onchain.activity.detected"]

isEnabled

boolean

required

Whether the subscription is enabled.

Example:

true

target

object

required

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

Show child attributes

Example:

{
  "url": "https://api.example.com/webhooks",
  "headers": {
    "Authorization": "Bearer token123",
    "Content-Type": "application/json"
  }
}

description

string

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

Maximum string length: 100

Example:

"Subscription for token transfer events"

metadata

object

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

Show child attributes

Example:

{ "foo": "bar", "baz": "qux" }

labels

object

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.

Show child attributes

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 created 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

A webhook event type identifier following dot-separated format: <domain>.<entity>.<verb> (e.g., "onchain.activity.detected").

Available options:

onchain.activity.detected,

wallet.activity.detected,

wallet.activity.multi,

wallet.transaction.created,

wallet.transaction.signed,

wallet.transaction.broadcast,

wallet.transaction.replaced,

wallet.transaction.pending,

wallet.transaction.confirmed,

wallet.transaction.failed,

wallet.delegation.created,

wallet.delegation.revoked,

wallet.typed_data.signed,

wallet.message.signed,

wallet.hash.signed,

payments.transfers.quoted,

payments.transfers.processing,

payments.transfers.completed,

payments.transfers.failed,

payments.transfers.expired,

payments.transfers.travel_rule_incomplete,

payments.transfers.travel_rule_completed,

onramp.transaction.created,

onramp.transaction.updated,

onramp.transaction.success,

onramp.transaction.failed,

offramp.transaction.created,

offramp.transaction.updated,

offramp.transaction.success,

offramp.transaction.failed,

acceptance.payment_session.created,

acceptance.payment_session.canceled,

acceptance.payment_session.authorization_pending,

acceptance.payment_session.authorization_succeeded,

acceptance.payment_session.authorization_failed,

acceptance.payment_session.capture_pending,

acceptance.payment_session.capture_succeeded,

acceptance.payment_session.capture_failed,

acceptance.payment_session.refund_pending,

acceptance.payment_session.refund_succeeded,

acceptance.payment_session.refund_failed,

acceptance.payment_session.void_pending,

acceptance.payment_session.void_succeeded,

acceptance.payment_session.void_failed,

acceptance.disbursement.pending,

acceptance.disbursement.succeeded,

acceptance.disbursement.failed,

health.status.updated,

health.maintenance.scheduled,

health.maintenance.started,

health.maintenance.completed,

health.maintenance.canceled,

customers.capability.changed,

customers.customer.deleted

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.

Show child attributes

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

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

Maximum string length: 100

Example:

"Subscription for token transfer events"

metadata

object

Additional metadata for the subscription.

Show child attributes

Example:

{
  "customer_id": "cust_12345",
  "order_reference": "order-67890",
  "secret": "123e4567-e89b-12d3-a456-426614174000"
}

labels

object

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.

Show child attributes

Examples:

{
  "network": "base-mainnet",
  "contract_address": "0xcd1f9777571493aeacb7eae45cd30a226d3e612d",
  "event_name": "Burn"
}

{
  "network": "base-mainnet",
  "params.from": "0x3E16D476D8Df15e3E776EAa5A46f37EC44C830cD"
}

{
  "network": "base-mainnet",
  "wallet_addresses": "0x3e16d476d8df15e3e776eaa5a46f37ec44c830cd"
}

{ "service": "webhooks" }

{
  "project": "project_123e4567-e89b-12d3-a456-426614174000"
}

{
  "entity": "entity_123e4567-e89b-12d3-a456-426614174000"
}

{
  "user_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "sandbox": "false"
}

CDP API

REST API

Webhook Signature Verification

Authorizations

Body

Label Behavior

Response