Webhook events

This page lists every event Aeses can deliver. Each event includes a full snapshot of the resource in data (see the payload shape) — you do not need to fetch the resource again, unless you need state that changed after the event was queued.

Deposit events

`deposit.created`

Fired when a new deposit address is generated. The customer has not paid yet.

Sample payload

{
"id": "evt_01j9x7m2p5rt",
"event": "deposit.created",
"created_at": 1731598200,
"data": {
  "object": "deposit",
  "id": "dep_3f2a9c1e7b8d4a6f9e0c1b2a3d4e5f60",
  "status": "pending",
  "asset": "USDC",
  "chain": "ethereum",
  "expected_amount": "99.50",
  "received_amount": null,
  "deposit_address": "0x8f3a...8A9",
  "reference_id": "order_1042",
  "webhook_url": "https://example.com/webhooks/aeses",
  "metadata": null,
  "tx_hash": null,
  "confirmations": 0,
  "expires_at": 1731600000,
  "created_at": 1731598200
}
}

`deposit.confirming`

The first on-chain confirmation has been seen. Funds are not yet credited to your balance — wait for deposit.completed. Useful for showing a "Payment received, awaiting confirmations" state in your UI.

`deposit.completed`

The deposit has reached the network-specific confirmation threshold and the amount has been credited to your internal balance. This is the canonical "money has arrived" event.

`deposit.underpaid`

The deposit completed, but the received amount was less than expected_amount. The funds are credited; reconcile the difference with the customer.

`deposit.overpaid`

The deposit completed with more than expected_amount. The full amount is credited; treat the overage according to your business rules.

`deposit.expired`

The deposit address window (30 minutes) passed without enough confirmations. Funds sent after expiry are still credited but may require manual reconciliation in the dashboard.

`deposit.cancelled`

The deposit was cancelled (by you via the API or by our operations team). Funds are not credited.

Withdrawal events

Withdrawal events are delivered to the webhook_url sent when the withdrawal was created. The body is:

Sample payload — withdrawal.broadcasted

{
"id": "evt_k3j9x0a1b2c3",
"event": "withdrawal.broadcasted",
"created_at": 1731600360,
"data": {
  "object": "withdrawal",
  "id": "wd_3f2a9c1e7b8d4a6f9e0c1b2a3d4e5f60",
  "status": "broadcasted",
  "asset": "USDT",
  "chain": "ethereum",
  "amount": "150.00000000",
  "fee": "1.25000000",
  "net_amount": null,
  "address": "0xRecipient...",
  "tx_hash": "0xabc123...",
  "reference_id": "po_8821",
  "webhook_url": "https://example.com/webhooks/aeses",
  "metadata": null,
  "fail_reason": null,
  "created_at": 1731600300
}
}

`withdrawal.created`

A new withdrawal has been accepted into the queue. The on-chain transaction has not yet been broadcast.

`withdrawal.processing`

The withdrawal was approved and is queued for signing. Only sent for withdrawals that required manual approval.

`withdrawal.broadcasted`

The transaction has been signed and broadcast to the network; data.tx_hash is set. The recipient has not been paid yet — the transaction still needs to be mined and confirmed, and can still be dropped or reverted. Show it as "processing" in your UI.

`withdrawal.completed`

The transaction was mined successfully and reached the network's confirmation threshold. This is the canonical "recipient was paid" event. Your balance was debited at creation time, not now.

`withdrawal.failed`

The withdrawal failed permanently (e.g. network rejection, reverted transaction, or a transaction dropped by the network). Your balance is refunded automatically. data.fail_reason explains why. This event can arrive after withdrawal.broadcasted.

`withdrawal.cancelled`

The withdrawal was cancelled before broadcast. Your balance is refunded.

Handling withdrawal events

Treat a withdrawal as paid only on withdrawal.completed.
Events can be retried and, exceptionally, re-sent (e.g. after a manual review by our operations team). Deduplicate by data.id + event and make your handler idempotent.
Apply status by precedence, not arrival order: completed, failed and cancelled are final; never move a final withdrawal back to broadcasted.
Use data.tx_hash from the latest event — it can change between broadcasted and completed in the rare case where the original transaction was dropped and the payout settled through another one.
If you need the current state, call GET /v1/withdrawals/:id.

Event metadata

Beyond data, every event includes:

| Field | Description | | ------------ | ------------------------------------------------------ | | id | Unique event ID. | | event | One of the values above. | | created_at | Unix timestamp (seconds) when the event was generated. |

To deduplicate, use data.id + event (or the X-Webhook-Id header for retries of the same delivery).

Subscribing to specific events

By default, all events are delivered to all configured webhook endpoints. You can filter events per endpoint in Dashboard → Developers → Webhooks. Filtering is a server-side feature — your endpoint will simply not receive events it is not subscribed to.