Wallet action webhooks

Privy emits webhooks when wallet actions change status, allowing your app to react to swaps, transfers, and earn activity in real time without polling.

Setup

Subscribe to wallet action events from the Configuration > Webhooks page in the Privy Dashboard. For general webhook setup instructions, payload verification, and retry behavior, see the webhooks overview.

Webhooks can be tested at no cost in development environments. To enable webhooks in production, upgrade to the Enterprise plan in the Privy Dashboard.

Statuses

Every wallet action moves through a predictable status lifecycle. Privy emits a webhook at each status update.

Status	Description
`'created'`	Wallet action has been queued for execution and resource ID has been returned to the caller.
`'succeeded'`	All steps of the wallet action have successfully executed. This is a terminal state.
`'rejected'`	The wallet action was rejected prior to executing any steps, e.g. due to a policy violation. This is a terminal state and safe to retry.
`'failed'`	The wallet action failed during execution of one of its steps. Use the get wallet action endpoint with `?include=steps` to inspect what went wrong at the step level.

Action-specific payloads

All wallet action webhook payloads include a type (event name), status, and action id. Beyond these fields, payloads will include the fields present in that wallet action’s resource.

For example, the payloads for wallet_action.transfer.* webhooks include the fields when calling fetching the transfer action resource via GET /v1/actions/{action_id} where action_id corresponds to a transfer.

View the payloads for specific wallet actions below. Click the webhook event name to be redirected to its payload schema.

Transfer

Event	Description
`wallet_action.transfer.created`	A transfer action is created and queued
`wallet_action.transfer.succeeded`	The transfer transaction confirms onchain
`wallet_action.transfer.rejected`	The transfer is rejected before broadcast
`wallet_action.transfer.failed`	The transfer transaction fails after broadcast

Swap

Event	Description
`wallet_action.swap.created`	A swap action is created and queued
`wallet_action.swap.succeeded`	The swap transaction confirms onchain
`wallet_action.swap.rejected`	The swap is rejected before broadcast
`wallet_action.swap.failed`	The swap transaction fails after broadcast

Earn

View a more detailed explanation of earn webhooks.

Deposit

Event	Description
`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 fails after broadcast

Withdraw

Event	Description
`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 fails after broadcast

Claim incentive

Event	Description
`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 fails after broadcast

​Setup

​Statuses

​Action-specific payloads

​Transfer

​Swap

​Earn

​Deposit

​Withdraw

​Claim incentive

Setup

Statuses

Action-specific payloads

Transfer

Swap

Earn

Deposit

Withdraw

Claim incentive