Setup
Subscribe to earn events from the Configuration > Webhooks page in the Privy Dashboard.Webhooks can be tested at no cost in development environments. To enable webhooks in production,
upgrade to the Enterprise plan in the Privy Dashboard.
Status lifecycle
Every earn action (deposit, withdraw, incentive claim) moves through a predictable status lifecycle. Privy emits a webhook at each transition.Created
The action is received and queued for processing. At this point, no transaction has been signed or broadcast.
Succeeded, rejected, or failed
The action reaches a terminal state:
- Succeeded — the transaction confirmed onchain.
- Rejected — the action failed before any transaction was signed or broadcast (e.g. insufficient balance, policy violation). Safe to retry.
- Failed — a transaction was broadcast but reverted onchain. Inspect the action’s
stepsfor details.
Event reference
Deposit events
Fired when a wallet deposits assets into a yield vault.| Event | Fired when |
|---|---|
wallet_action.earn_deposit.created | A deposit action is created and queued |
wallet_action.earn_deposit.succeeded | The deposit transaction confirms onchain |
wallet_action.earn_deposit.rejected | The deposit is rejected before broadcast |
wallet_action.earn_deposit.failed | The deposit transaction reverts onchain |
Withdrawal events
Fired when a wallet redeems vault shares for the underlying asset plus accrued yield.| Event | Fired when |
|---|---|
wallet_action.earn_withdraw.created | A withdrawal action is created and queued |
wallet_action.earn_withdraw.succeeded | The withdrawal transaction confirms onchain |
wallet_action.earn_withdraw.rejected | The withdrawal is rejected before broadcast |
wallet_action.earn_withdraw.failed | The withdrawal transaction reverts onchain |
Incentive claim events
Fired when a wallet claims additional token rewards distributed by the vault.| Event | Fired when |
|---|---|
wallet_action.earn_incentive_claim.created | A claim action is created and queued |
wallet_action.earn_incentive_claim.succeeded | The claim transaction confirms onchain |
wallet_action.earn_incentive_claim.rejected | The claim is rejected before broadcast |
wallet_action.earn_incentive_claim.failed | The claim transaction reverts onchain |
Common patterns
Update user balances after a deposit
Update user balances after a deposit
Listen for
wallet_action.earn_deposit.succeeded to refresh the user’s position. Once the
webhook fires, call the get position endpoint to
fetch the updated assets_in_vault balance and display it in your UI.Notify users when a withdrawal completes
Notify users when a withdrawal completes
Listen for
wallet_action.earn_withdraw.succeeded to trigger a notification. The webhook
payload includes the wallet_id and vault_id, which your app can use to look up the user and
send an in-app or push notification.Handle rejected actions gracefully
Handle rejected actions gracefully
A
rejected status means no transaction was broadcast — for example, due to insufficient
balance or a policy violation. Your app can safely prompt the user to retry. Check the action’s
error details to surface a helpful message.Detect failed transactions
Detect failed transactions
A
failed status means a transaction was broadcast but reverted onchain. Use the get wallet
action endpoint with ?include=steps to inspect what went
wrong. Common causes include vault liquidity shortfalls or gas estimation issues.