Create webhook subscription
Subscribe to real-time events across CDP products using flexible filtering.
Event Types
Onchain Events - Monitor Base mainnet with microsecond precision:
onchain.activity.detected- Smart contract events, transfers, swaps, NFT activity- Requires
labelsfor filtering (e.g.,contract_address,event_name)
Onramp/Offramp Events - Transaction lifecycle notifications:
onramp.transaction.created,onramp.transaction.updatedonramp.transaction.success,onramp.transaction.failedofframp.transaction.created,offramp.transaction.updatedofframp.transaction.success,offramp.transaction.failed- No labels required - maximum simplicity for transaction monitoring
Payments Transfers Events - Transfer lifecycle notifications:
payments.transfers.quoted- Transfer created and awaiting executionpayments.transfers.processing- Transfer execution in progresspayments.transfers.completed- Transfer completed successfullypayments.transfers.failed- Transfer failedpayments.transfers.travel_rule_incomplete- Travel rule information is missingpayments.transfers.travel_rule_completed- Travel rule information has been provided and the transfer will proceed- No labels required - enable the transfers webhook to monitor status transitions
Wallet Events - Wallet activity notifications:
wallet.activity.detected
Webhook Signature Verification
All webhooks include cryptographic signatures for security.
The signature secret is returned in secret field when creating a subscription.
Note: Webhooks are in beta and this interface is subject to change.
See the verification guide for implementation details.
Onchain Label Filtering
For onchain.activity.detected events, use labels for precise filtering with AND logic (max 20 labels per webhook).
Allowed labels (all in snake_case format):
network(required) - Blockchain networkcontract_address- Smart contract addressevent_name- Event name (e.g., “Transfer”, “Burn”)event_signature- Event signature hashtransaction_from- Transaction sender addresstransaction_to- Transaction recipient addressparams.*- Any event parameter (e.g.,params.from,params.to,params.sender,params.tokenId)
Examples:
- Liquidity Pool Monitor:
{"network": "base-mainnet", "contract_address": "0xcd1f9777571493aeacb7eae45cd30a226d3e612d", "event_name": "Burn"} - Price Oracle Tracker:
{"network": "base-mainnet", "contract_address": "0xbac4a9428ea707c51f171ed9890c3c2fa810305d", "event_name": "PriceUpdated"} - DeFi Protocol Activity:
{"network": "base-mainnet", "contract_address": "0x45c6e6a47a711b14d8357d5243f46704904578e3", "event_name": "Deposit"}
Authorizations
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
Request to create a new webhook subscription with support for multi-label filtering.
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", "acceptance.payment_session"). The subscription will only receive events matching these types AND the label filter(s).
["onchain.activity.detected"]Whether the subscription is enabled.
true
Target configuration for webhook delivery. Specifies the destination URL and any custom headers to include in webhook requests.
{
"url": "https://api.example.com/webhooks",
"headers": {
"Authorization": "Bearer token123",
"Content-Type": "application/json"
}
}Description of the webhook subscription.
500"Subscription for token transfer events"
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.
{
"customer_id": "cust_12345",
"order_reference": "order-67890"
}Optional. 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. Additional labels on the event are allowed and will not prevent matching. Omit to receive all events for the selected event types.
Note: Currently, labels are supported for onchain webhooks only.
{
"network": "base-mainnet",
"contract_address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"event_name": "Transfer"
}Response
Webhook subscription created successfully.
Response containing webhook subscription details.
When the subscription was created.
"2025-01-15T10:30:00Z"
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", "acceptance.payment_session").
["onchain.activity.detected"]Whether the subscription is enabled.
true
Secret for webhook signature validation.
"123e4567-e89b-12d3-a456-426614174000"
Unique identifier for the subscription.
"123e4567-e89b-12d3-a456-426614174000"
Target configuration for webhook delivery. Specifies the destination URL and any custom headers to include in webhook requests.
{
"url": "https://api.example.com/webhooks",
"headers": {
"Authorization": "Bearer token123",
"Content-Type": "application/json"
}
}When the subscription was last updated.
"2025-01-16T14:00:00Z"
Description of the webhook subscription.
500"Subscription for token transfer events"
Additional metadata for the subscription.
{
"customer_id": "cust_12345",
"order_reference": "order-67890",
"secret": "123e4567-e89b-12d3-a456-426614174000"
}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.
{
"env": "dev",
"team": "payments",
"contract_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
}