Skip to main content
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. JSON payload shapes are in the Deposit payload reference. See 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 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).
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.

​
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.

​
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

Below-minimum alerts are delivered through the standard Deposit Webhook endpoint.
  1. Create a deposit webhook using POST /v1/webhook/deposit/api-key (see Create a Deposit Webhook).
  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.
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.

​
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.

​
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

Under-review alerts are delivered through the standard Deposit Webhook endpoint.
  1. Create a deposit webhook using POST /v1/webhook/deposit/api-key (see Create a Deposit Webhook).
  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.
Not a completed deposit: DEPOSIT_UNDER_REVIEW is fired when funds are held, not swept. No DEPOSIT_TX_* events will follow for held funds.
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.
Best-effort delivery: Webhook delivery is best-effort. The dashboard and transaction explorer UNDER_REVIEW badge are the authoritative pull surfaces for held deposits.

​
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 you create per UTC day, not individual deposit transactions.

​
Setup

Quota alerts are delivered through the standard Deposit Webhook endpoint.
  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.
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.