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

# Deposit webhook events

> Payloads for deposit.action_required, deposit.success, and deposit.failed.

Deposit events contain a public wallet transaction snapshot under
`data.transaction`. Subscribe to one or more exact event names; `deposit.*` is
not supported.

| Event                     | When it is sent                                                         |
| ------------------------- | ----------------------------------------------------------------------- |
| `deposit.action_required` | A crypto deposit is on hold until Travel Rule information is submitted. |
| `deposit.success`         | A fiat or crypto deposit reached its successful terminal state.         |
| `deposit.failed`          | A fiat or crypto deposit reached its failed terminal state.             |

## `deposit.action_required`

This event has `status: "hold"` and a `required_action` object. Follow the
relative `submission_url` with the same Partner API host and authentication used
for wallet requests.

```json theme={null}
{
  "id": "9f511315-90c9-5fc7-95a0-a79e72b4a425",
  "type": "deposit.action_required",
  "version": 1,
  "occurred_at": "2026-07-17T09:40:00Z",
  "data": {
    "transaction": {
      "id": "019bd2d1-4e10-77ab-88d4-93f43d6a6df2",
      "rail": "crypto",
      "currency": "USD",
      "tx_type": "deposit",
      "status": "hold",
      "amount": "100.00",
      "reference": null,
      "description": null,
      "failure_reason": null,
      "settlement_rail": "USDC",
      "required_action": {
        "type": "travel_rule",
        "status": "required",
        "submission_url": "/partner/wallets/crypto/deposits/019bd2d1-4e10-77ab-88d4-93f43d6a6df2/travel-rule"
      },
      "created_at": "2026-07-17T09:38:41+00:00",
      "updated_at": "2026-07-17T09:40:00+00:00",
      "settlement_details": {
        "type": "crypto",
        "rail_reference": "019bd2d1-4e10-77ab-88d4-93f43d6a6df2",
        "blockchain_tx_hash": null,
        "explorer_url": null,
        "sender_address": null,
        "destination_address": null,
        "beneficiary_nickname": null,
        "network": null,
        "network_display": null,
        "principal_amount": null,
        "network_fee": null,
        "block_number": null,
        "confirmations": null,
        "confirmed_at": null,
        "failed_at": null
      }
    }
  }
}
```

## `deposit.success`

The snapshot is deliberately minimal and immutable. Later settlement details
such as bank account details, blockchain hashes, and confirmation counts are not
included in the webhook body. Read the transaction resource when you need its
latest details.

```json theme={null}
{
  "id": "0eddb359-f13e-5183-9337-31cb7e275d6b",
  "type": "deposit.success",
  "version": 1,
  "occurred_at": "2026-07-17T09:42:18Z",
  "data": {
    "transaction": {
      "id": "019bd2d1-58ac-7d3d-b2b1-36c5d9bf0272",
      "rail": "fiat",
      "currency": "NGN",
      "tx_type": "deposit",
      "status": "success",
      "amount": "250000.00",
      "reference": null,
      "description": null,
      "failure_reason": null,
      "created_at": "2026-07-17T09:41:02+00:00",
      "updated_at": "2026-07-17T09:42:18+00:00",
      "settlement_details": {
        "type": "bank_transfer",
        "rail_reference": "019bd2d1-58ac-7d3d-b2b1-36c5d9bf0272",
        "confirmed_at": "2026-07-17T09:42:18+00:00",
        "failed_at": null
      }
    }
  }
}
```

## `deposit.failed`

The public `failure_reason` is normalized and does not expose raw rail or
internal accounting details.

```json theme={null}
{
  "id": "c902d7ed-5ef1-5d7c-9032-a9d63a39b47d",
  "type": "deposit.failed",
  "version": 1,
  "occurred_at": "2026-07-17T09:45:31Z",
  "data": {
    "transaction": {
      "id": "019bd2d1-63bb-7a95-a9b4-cd9270c1b32a",
      "rail": "fiat",
      "currency": "NGN",
      "tx_type": "deposit",
      "status": "failed",
      "amount": "250000.00",
      "reference": null,
      "description": null,
      "failure_reason": "deposit_failed",
      "created_at": "2026-07-17T09:44:57+00:00",
      "updated_at": "2026-07-17T09:45:31+00:00",
      "settlement_details": {
        "type": "bank_transfer",
        "rail_reference": "019bd2d1-63bb-7a95-a9b4-cd9270c1b32a",
        "confirmed_at": null,
        "failed_at": "2026-07-17T09:45:31+00:00"
      }
    }
  }
}
```

## Reconcile the resource

Use `data.transaction.id` with
`GET /v1/partner/wallets/transactions/{id}`. The REST response is authoritative
and may contain newer display or settlement information than the immutable
webhook snapshot.

[Return to the webhook overview](/docs/webhooks)