> ## Documentation Index
> Fetch the complete documentation index at: https://docs.privy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Track earn deposit, withdrawal, and incentive claim activity with real-time webhooks.

Privy emits webhooks when earn wallet actions change status, allowing your app to react to deposits, withdrawals, and incentive claims in real time without polling.

## Setup

Subscribe to earn events from the **Configuration > Webhooks** page in the [Privy Dashboard](https://dashboard.privy.io/apps?page=webhooks).

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

For general webhook setup instructions, payload verification, and retry behavior, see the [webhooks overview](/api-reference/webhooks/overview).

## Status lifecycle

Every earn action (deposit, withdraw, incentive claim) moves through a predictable status lifecycle. Privy emits a webhook at each transition.

<Steps>
  <Step title="Created">
    The action is received and queued for processing. At this point, no transaction has been signed or broadcast.
  </Step>

  <Step title="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 `steps` for details.
  </Step>
</Steps>

## Event reference

### Deposit events

Fired when a wallet deposits assets into a yield vault.

| Event                                                                                                  | Fired when                               |
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------- |
| [`wallet_action.earn_deposit.created`](/api-reference/webhooks/wallet-action/earn-deposit/created)     | A deposit action is created and queued   |
| [`wallet_action.earn_deposit.succeeded`](/api-reference/webhooks/wallet-action/earn-deposit/succeeded) | The deposit transaction confirms onchain |
| [`wallet_action.earn_deposit.rejected`](/api-reference/webhooks/wallet-action/earn-deposit/rejected)   | The deposit is rejected before broadcast |
| [`wallet_action.earn_deposit.failed`](/api-reference/webhooks/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`](/api-reference/webhooks/wallet-action/earn-withdraw/created)     | A withdrawal action is created and queued   |
| [`wallet_action.earn_withdraw.succeeded`](/api-reference/webhooks/wallet-action/earn-withdraw/succeeded) | The withdrawal transaction confirms onchain |
| [`wallet_action.earn_withdraw.rejected`](/api-reference/webhooks/wallet-action/earn-withdraw/rejected)   | The withdrawal is rejected before broadcast |
| [`wallet_action.earn_withdraw.failed`](/api-reference/webhooks/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`](/api-reference/webhooks/wallet-action/earn-incentive-claim/created)     | A claim action is created and queued   |
| [`wallet_action.earn_incentive_claim.succeeded`](/api-reference/webhooks/wallet-action/earn-incentive-claim/succeeded) | The claim transaction confirms onchain |
| [`wallet_action.earn_incentive_claim.rejected`](/api-reference/webhooks/wallet-action/earn-incentive-claim/rejected)   | The claim is rejected before broadcast |
| [`wallet_action.earn_incentive_claim.failed`](/api-reference/webhooks/wallet-action/earn-incentive-claim/failed)       | The claim transaction reverts onchain  |

## Common patterns

<AccordionGroup>
  <Accordion title="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](/api-reference/wallets/earn/get-position) endpoint to
    fetch the updated `assets_in_vault` balance and display it in your UI.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Detect failed transactions">
    A `failed` status means a transaction was broadcast but reverted onchain. Use the [get wallet
    action](/api-reference/wallets/actions/get) endpoint with `?include=steps` to inspect what went
    wrong. Common causes include vault liquidity shortfalls or gas estimation issues.
  </Accordion>
</AccordionGroup>