Skip to main content
WEBHOOK

Authorizations

​
X-Webhook-Signature
string
header
required

HMAC-SHA256 signature supplied on every webhook delivery. The signature is computed from the raw request body using the webhook secret supplied during creation of the webhook subscription.

Webhook receivers can cryptographically verify this header before processing the event to ensure the authenticity of the webhook delivery.

Refer to the verify signatures documentation to learn details about the full payload and the exact verification algorithm.

X-Hook0-Signature is deprecated and will eventually be removed. Use X-Webhook-Signature going forward. Both headers are sent with identical values and use the same verification algorithm and webhook secret.

This scheme applies to webhook delivery (outbound POSTs from CDP to your endpoint), not to inbound CDP API requests.

Headers

​
X-Webhook-Signature
string
required

HMAC-SHA256 signature supplied on every webhook delivery. The signature is computed from the raw request body using the webhook secret supplied during creation of the webhook subscription.

Webhook receivers can cryptographically verify this header before processing the event to ensure the authenticity of the webhook delivery.

Refer to the verify signatures documentation to learn details about the full payload and the exact verification algorithm.

X-Hook0-Signature is deprecated and will eventually be removed. Use X-Webhook-Signature going forward. Both headers are sent with identical values and use the same verification algorithm and webhook secret.

This scheme applies to webhook delivery (outbound POSTs from CDP to your endpoint), not to inbound CDP API requests.

​
X-Hook0-Signature
string
required

HMAC-SHA256 signature supplied on every webhook delivery. The signature is computed from the raw request body using the webhook secret supplied during creation of the webhook subscription.

Webhook receivers can cryptographically verify this header before processing the event to ensure the authenticity of the webhook delivery.

Refer to the verify signatures documentation to learn details about the full payload and the exact verification algorithm.

X-Hook0-Signature is deprecated and will eventually be removed. Use X-Webhook-Signature going forward. Both headers are sent with identical values and use the same verification algorithm and webhook secret.

This scheme applies to webhook delivery (outbound POSTs from CDP to your endpoint), not to inbound CDP API requests.

Body

application/json

The onramp.transaction.success webhook event payload.

Webhook payload for all onramp transaction events (created, updated, success, failed). Shape depends on transaction type — standard flow (guest checkout / authorized) uses OnrampTransactionPayload, Headless API (Apple Pay / Google Pay) uses OnrampOrderPayload. Distinguish by presence of orderId (Headless) vs transactionId (standard).

​
eventType
string
required

The webhook event type.

Example:

"onramp.transaction.updated"

​
transactionId
string
required

Unique transaction identifier.

Example:

"1f087a54-ff1f-62e8-9f85-aa77ac0499a5"

​
status
enum<string>
required

Current status of the transaction.

Available options:
ONRAMP_TRANSACTION_STATUS_UNSPECIFIED,
ONRAMP_TRANSACTION_STATUS_CREATED,
ONRAMP_TRANSACTION_STATUS_IN_PROGRESS,
ONRAMP_TRANSACTION_STATUS_SUCCESS,
ONRAMP_TRANSACTION_STATUS_FAILED,
ONRAMP_TRANSACTION_STATUS_AWAITING_AUTH,
ONRAMP_TRANSACTION_STATUS_AWAITING_PAYMENT
Example:

"ONRAMP_TRANSACTION_STATUS_IN_PROGRESS"

​
purchaseCurrency
string

The crypto currency purchased (e.g., "USDC", "ETH").

Example:

"USDC"

​
purchaseNetwork
string

The blockchain network for the purchase (e.g., "ethereum", "base").

Example:

"ethereum"

​
purchaseAmount
object

A monetary amount with currency.

Example:
​
paymentTotal
object

A monetary amount with currency.

Example:
​
paymentTotalUsd
object

A monetary amount with currency.

Example:
​
paymentSubtotal
object

A monetary amount with currency.

Example:
​
coinbaseFee
object

A monetary amount with currency.

Example:
​
networkFee
object

A monetary amount with currency.

Example:
​
exchangeRate
object

A monetary amount with currency.

Example:
​
txHash
string

The onchain transaction hash of the send (0x-prefixed for EVM).

Example:

"0x"

​
createdAt
string<date-time>

When the transaction was created.

Example:

"2025-09-02T02:34:13Z"

​
completedAt
string<date-time>

When the transaction completed (uses send_started_at for early success).

Example:

"0001-01-01T00:00:00Z"

​
country
string

The user's country code.

Example:

"US"

​
userId
string

Hashed user identifier (entity hash for guest, user ID for authed).

Example:

"4132b63ee21128686458155b28570289"

​
paymentMethod
enum<string>

The payment method used.

Available options:
UNSPECIFIED,
CARD,
ACH_BANK_ACCOUNT,
APPLE_PAY,
FIAT_WALLET,
CRYPTO_ACCOUNT,
GUEST_CHECKOUT_CARD,
PAYPAL,
RTP,
GUEST_CHECKOUT_APPLE_PAY,
GUEST_CHECKOUT_GOOGLE_PAY
Example:

"CARD"

​
walletAddress
string

The destination wallet address.

Example:

"0xe0512E358C347cc2b1A42d057065CE642068b7Ba"

​
type
enum<string>

The type of onramp transaction.

Available options:
ONRAMP_TRANSACTION_TYPE_UNSPECIFIED,
ONRAMP_TRANSACTION_TYPE_BUY_AND_SEND,
ONRAMP_TRANSACTION_TYPE_SEND
Example:

"ONRAMP_TRANSACTION_TYPE_BUY_AND_SEND"

​
userType
enum<string>

Whether the user is authed or guest.

Available options:
USER_TYPE_UNSPECIFIED,
USER_TYPE_AUTHED,
USER_TYPE_GUEST
Example:

"USER_TYPE_GUEST"

​
partnerUserRef
string

The partnerUserId provided when initializing the onramp session.

Example:

"example_user_ref"

​
contractAddress
string

The token contract address (populated when asset metadata is available).

Example:

""

​
failureReason
enum<string>

The reason for failure (if applicable).

Available options:
FAILURE_REASON_UNSPECIFIED,
FAILURE_REASON_BUY_FAILED,
FAILURE_REASON_SEND_FAILED
Example:

"FAILURE_REASON_UNSPECIFIED"

​
endPartnerName
string

The name of the developer app.

Example:

""

​
errorCode
string

Error code for the transaction failure (if applicable).

Example:

"ERROR_CODE_UNSPECIFIED"

​
partnerId
string

The Onramp-issued identifier of the end partner this transaction was scoped to via the X-Onramp-Partner-Id header on the session that initiated it. Only present for transactions created by an aggregator on behalf of a registered end partner.

Example:

"1f1c19e8-d0e9-6443-b706-92a4d033d043"

Response

Webhook received and processed successfully.