Onramp webhooks provide your app with real-time transaction status updates. By subscribing your webhook endpoint you will receive a notification every time a transaction made by your users is created or updated.
Webhooks are currently in private Alpha, and only available for Guest checkout transactions.

​
Setup

​
Prerequisites

You will need:
  • Your CDP API Key ID and secret
  • Your CDP project ID
  • A webhook notification HTTPS URL
  • (Recommended) Install cdpcurl

​
Create a webhook subscription

  1. Prepare your subscription configuration:
{
  "description": "Onramp Guest transaction status webhook",
  "eventTypes": [
    "onramp.transaction.created",
    "onramp.transaction.updated", 
    "onramp.transaction.success",
    "onramp.transaction.failed"
  ],
  "target": {
    "url": "https://your-webhook-url.com",
    "method": "POST"
  },
  "labelKey": "project",
  "labelValue": "YOUR_PROJECT_ID",
  "isEnabled": true
}
Important configuration notes:
  • labelKey must be set to "project"
  • labelValue must be your CDP project ID
  • target.url should be your webhook endpoint that will receive the events
  • All four event types should be included to ensure you receive notifications for every transaction state change
Event typeDescription
onramp.transaction.createdNew transaction created
onramp.transaction.updatedTransaction status changed
onramp.transaction.successTransaction completed successfully
onramp.transaction.failedTransaction failed
  1. Create the webhook subscription:
cdpcurl -X POST \
  -i "YOUR_API_KEY_ID" \
  -s "YOUR_API_KEY_SECRET" \
  "https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions" \
  -d '{
    "description": "Onramp Guest transaction status webhook",
    "eventTypes": [
      "onramp.transaction.created",
      "onramp.transaction.updated",
      "onramp.transaction.success",
      "onramp.transaction.failed"
    ],
    "target": {
      "url": "https://your-webhook-url.com",
      "method": "POST"
    },
    "labelKey": "project",
    "labelValue": "YOUR_PROJECT_ID",
    "isEnabled": true
  }'
Once you’ve created the webhook subscription, you can use the subscriptionId from the response to view, update, or delete the subscription. View subscription details 
cdpcurl -X GET \
  -i "YOUR_API_KEY_ID" \
  -s "YOUR_API_KEY_SECRET" \
  "https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions/<SUBSCRIPTION_ID>"
Update subscription 
cdpcurl -X PUT \
  -i "YOUR_API_KEY_ID" \
  -s "YOUR_API_KEY_SECRET" \
  "https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions/<SUBSCRIPTION_ID>" \
  -d '{
    "description": "Updated: Onramp Guest transaction status webhook",
    "eventTypes": [
      "onramp.transaction.created",
      "onramp.transaction.updated",
      "onramp.transaction.success",
      "onramp.transaction.failed"
    ],
    "target": {
      "url": "https://your-new-webhook-url.com",
      "method": "POST"
    },
    "labelKey": "project",
    "labelValue": "YOUR_PROJECT_ID",
    "isEnabled": true
  }'
Delete subscription 
cdpcurl -X DELETE \
  -i "YOUR_API_KEY_ID" \
  -s "YOUR_API_KEY_SECRET" \
  "https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions/<SUBSCRIPTION_ID>"

​
Next steps

Once your subscription is created, your endpoint will begin receiving webhook events for Guest checkout transactions! Sample webhook event payload 
{
  "coinbaseFee": {
    "currency": "USD",
    "value": "0"
  },
  "completedAt": "0001-01-01T00:00:00Z",
  "country": "US",
  "createdAt": "2025-09-02T02:34:13Z",
  "exchangeRate": {
    "currency": "USDC",
    "value": "1"
  },
  "networkFee": {
    "currency": "USD",
    "value": "0.19"
  },
  "paymentMethod": "CARD",
  "paymentSubtotal": {
    "currency": "USD",
    "value": "4.81"
  },
  "paymentTotal": {
    "currency": "USD",
    "value": "5"
  },
  "paymentTotalUsd": {
    "currency": "USD",
    "value": "5"
  },
  "purchaseAmount": {
    "currency": "USDC",
    "value": "4.81"
  },
  "purchaseCurrency": "USDC",
  "purchaseNetwork": "ethereum",
  "status": "ONRAMP_TRANSACTION_STATUS_IN_PROGRESS",
  "transactionId": "1f087a54-ff1f-62e8-9f85-aa77ac0499a5",
  "txHash": "0x",
  "type": "ONRAMP_TRANSACTION_TYPE_BUY_AND_SEND",
  "userId": "4132b63ee21128686458155b28570289",
  "userType": "USER_TYPE_GUEST",
  "walletAddress": "0xe0512E358C347cc2b1A42d057065CE642068b7Ba"
}