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

# Deposit Webhooks

> Events, setup, and delivery rules for deposit webhooks

Deposit webhooks cover four categories: **transaction events** (per deposit), **below-minimum alerts** (per deposit wallet), **under-review alerts** (per deposit wallet), and **quota alerts** (per company).

Configure webhooks via [Create a Deposit Webhook](/reference/webhook/deposit/create). JSON payload shapes are in the [Deposit payload reference](/reference/webhook/deposit/payloads). See [Webhook request headers](/reference/webhook/overview#webhook-request-headers) for delivery headers.

## Transaction Events

We emit three webhook events when deposit transactions progress:

* `DEPOSIT_TX_SUBMITTED` — when the transaction is broadcast to the network, via [swaps.xyz](http://swaps.xyz) when a bridge or swap is involved.
* `DEPOSIT_TX_CONFIRMED` — when the transaction is confirmed on the blockchain.
* `DEPOSIT_TX_ENRICHED` — when the transaction is enriched with additional data.

Configure these on a deposit-scoped or global deposit webhook (see [Create a Deposit Webhook](/reference/webhook/deposit/create)).

<Info>
  `gasCharge` is currently always `"0"` for deposit webhooks. For swap or bridge deposits, `DEPOSIT_TX_SUBMITTED` may omit `transactionObject` and `transaction` when only sweep details are available at submission time.
</Info>

## Below-Minimum Deposit Alerts

The `DEPOSIT_BELOW_MINIMUM` event is sent when funds have been received in a deposit wallet but the balance has not yet reached the minimum amount required for settlement.

Use this event to notify users that additional funds are needed before their deposit can be processed. See the [below-minimum payload example](/reference/webhook/deposit/payloads#below-minimum-deposit-alerts).

### When it fires

The event is triggered when:

* A deposit wallet receives additional funds.
* The wallet balance is above the dust threshold.
* The balance remains below the minimum amount required for settlement.

### Setup

<Info>
  Below-minimum alerts are delivered through the standard Deposit Webhook endpoint.
</Info>

1. Create a deposit webhook using `POST /v1/webhook/deposit/api-key` (see [Create a Deposit Webhook](/reference/webhook/deposit/create)).
2. Both **deposit-scoped** webhooks (with a `depositId`) and **global** webhooks (without a `depositId`) receive `DEPOSIT_BELOW_MINIMUM` when subscribed.
3. New deposit webhooks default to `events: ["ALL"]`, which includes `DEPOSIT_BELOW_MINIMUM`. You can subscribe only to `DEPOSIT_BELOW_MINIMUM` if you prefer.
4. Authenticate deliveries with `Authorization` and verify `X-Signature` like other deposit webhooks.

<Warning>
  **Not a completed deposit:** `DEPOSIT_BELOW_MINIMUM` is fired before any sweep. Use `originalAmount` and `minimumAmount` (or their USD fields) to show how much more the user must send — for example, `minimumAmount - originalAmount` in source units.
</Warning>

## Under-Review Deposit Alerts

The `DEPOSIT_UNDER_REVIEW` event is sent when a deposit wallet is newly held for additional review before settlement can proceed. Funds remain in the deposit wallet and are not swept.

Use this event to notify users that their deposit is pending review. See the [under-review payload example](/reference/webhook/deposit/payloads#under-review-deposit-alerts).

### When it fires

The event is triggered when:

* A deposit wallet is newly placed under review.
* The wallet transitions to held status for the first time; the event fires **once per wallet**, not per deposit transaction.
* Re-deposits to an already-held wallet do **not** re-fire the event.

### Setup

<Info>
  Under-review alerts are delivered through the standard Deposit Webhook endpoint.
</Info>

1. Create a deposit webhook using `POST /v1/webhook/deposit/api-key` (see [Create a Deposit Webhook](/reference/webhook/deposit/create)).
2. Both **deposit-scoped** webhooks (with a `depositId`) and **global** webhooks (without a `depositId`) receive `DEPOSIT_UNDER_REVIEW` when subscribed.
3. New deposit webhooks default to `events: ["ALL"]`, which includes `DEPOSIT_UNDER_REVIEW`. You can subscribe only to `DEPOSIT_UNDER_REVIEW` if you prefer.
4. Authenticate deliveries with `Authorization` and verify `X-Signature` like other deposit webhooks.

<Warning>
  **Not a completed deposit:** `DEPOSIT_UNDER_REVIEW` is fired when funds are held, not swept. No `DEPOSIT_TX_*` events will follow for held funds.
</Warning>

<Warning>
  **No review details in payload:** The webhook payload intentionally omits the reason for the review and any related internal signals. Use `customerId` and `depositId` to identify the affected customer. For any further details, contact our team through your usual support channel.
</Warning>

<Warning>
  **Best-effort delivery:** Webhook delivery is best-effort. The dashboard and transaction explorer `UNDER_REVIEW` badge are the authoritative pull surfaces for held deposits.
</Warning>

## Deposit-Customer Quota Alerts

Company-level alerts fire when your account approaches its **daily deposit-customer creation** limit. These are separate from `DEPOSIT_TX_*` events: they track how many [deposit customers](/reference/deposit-customers/create) you create per UTC day, not individual deposit transactions.

| Event                             | Nominal threshold |
| --------------------------------- | ----------------- |
| `DEPOSIT_CUSTOMER_QUOTA_WARNING`  | \~80%             |
| `DEPOSIT_CUSTOMER_QUOTA_CRITICAL` | \~90%             |
| `DEPOSIT_CUSTOMER_QUOTA_REACHED`  | 100%              |

### Setup

<Info>
  Quota alerts are delivered through the standard Deposit Webhook endpoint.
</Info>

1. Create a **global** deposit webhook using `POST /v1/webhook/deposit/api-key` without a `depositId`.
2. Deposit-scoped webhooks (with a `depositId`) do **not** receive quota events.
3. New deposit webhooks are subscribed to all deposit events (`ALL`) by default, which includes quota alerts. If you already have a global deposit webhook, you will receive quota events without further configuration.

### Behaviour

* Alerts are triggered as deposit customers are created throughout the day.
* Each alert type is sent once per UTC day.
* Daily limits reset at midnight UTC.
* Once the limit is reached, further create requests return `429` until reset.

<Info>
  Quota alerts include `X-Webhook-Delivery-Id` in the format `<event>:<companyId>:<YYYY-MM-DD>`. The payload's `webhookDeliveryIdempotencyKey` uses the full ISO `resetsAt` timestamp instead of the date-only header format. See the [quota alert payload example](/reference/webhook/deposit/payloads#deposit-customer-quota-alerts).
</Info>