Deposit webhooks

INFO

Deposit webhooks for server wallets are not yet live in production. This guide is intended to be a preview of upcoming functionality.

Privy emits webhooks whenever a server wallet receives a transaction for a registered asset. This helps your application stay in sync with the assets in your server wallets, and easily track deposits.

To set up deposit webhooks, follow the guide below.

Setup a webhooks URL

To start, go to the Webhooks page for your app in the Privy Dashboard and provide a destination URL for receiving webhooks.

Then, enable the 'wallet.deposit_received' event. You can next configure which assets Privy should emit 'wallet.deposit_received' events for.

Privy will emit a signed webhook to this URL whenever your server wallets receive a transaction for a registered asset, and will retry delivery if the endpoint does not successfully respond to the original webhook.

Configure assets to track

Once you've enabled the 'wallet.deposit_received' event, you can then configure which assets you'd like to track via the Privy Dashboard.

Privy supports webhooks for native tokens (e.g. ETH, SOL) on EVM and Solana, ERC20 tokens on EVM, and SPL tokens on Solana.

Native tokens

To configure webhooks for native token transactions, simply select the Native token asset type and provide the CAIP-2 chain ID for the network on which to track the native token.

ERC20 tokens

To configure webhooks for ERC20 token transfers, simply select the ERC20 token asset type and provide:

• the contract address for the ERC20 token
• the CAIP-2 chain ID for the network on which to track the ERC20 token

SPL tokens

To configure webhooks for SPL token transfers, simply select the SPL token asset type and provide:

• the mint address for the SPL token
• the CAIP-2 chain ID for the network on which to track the SPL token

Payload

When a server wallet receives a transaction for a registered asset, Privy will emit a webhooks payload with the following fields:

Field	Type	Description
type	'wallet.deposit_received'	Event name for the webhook.
wallet_id	string	ID of the wallet that received the deposit.
asset	Object	Asset for the transaction.
asset.type	'native-token' | 'erc20' | 'spl'	Type of the asset for the transaction.
asset.address	string	Contract address for an ERC20 asset, or mint address for an SPL asset. This field will only be included for the 'erc20' and 'spl' asset.types.
amount	number	Absolute amount of the transaction. Denominated in the native unit for the asset (e.g. ETH, not gwei, for ETH; SOL, not lamports, for SOL).
transaction_hash	string	Hash for the transaction.
block	Object	Information about the block for the transaction
block.number	number	Number of the block for the transaction
sender	string	Sender of the transaction.
recipient	string	Recipient of the transaction.
caip2	string	CAIP-2 chain ID of the network where the transaction happened.

Example

Below is a sample webhooks payload that Privy might send on a deposit of 1000 USDC on Base into a server wallet.

{
  "event": "wallet.deposit_received",
  "wallet_id": "cm4db8x9t000ccn87pctvcg9j",
  "asset": {
    "type": "erc20",
    "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  },
  "amount": 10000,
  "transaction_hash": "0x2446f1fd773fbb9f080e674b60c6a033c7ed7427b8b9413cf28a2a4a6da9b56c",
  "sender": "0x59D3eB21Dd06A211C89d1caBE252676e2F3F2218",
  "recipient": "0x59D3eB21Dd06A211C89d1caBE252676e2F3F2218",
  "chain_id": "eip155:8453",
  "block": {
    "number": 22000002
  }
}