> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs-v3.openfx.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Deposit webhooks
> Receive a signed event when a fiat or stablecoin deposit completes or fails. Event envelope and Deposit resource shape.
OpenFX delivers a signed webhook event when a deposit transitions to a terminal state. Two event types cover the deposit lifecycle:
* **`deposit.completed`** — the deposit has been credited to your balance.
* **`deposit.failed`** — the deposit has reached a terminal failure state.
Both event types carry a single Deposit object in `data` that follows the same field conventions as v3 REST API responses — camelCase fields, string amounts, RFC 3339 timestamps.
## Event envelope
This routing-only example collapses `data` to an empty object. It deliberately omits the required Deposit fields shown in the complete, schema-checked examples below.
```json theme={null}
{
"id": "evt_7m4VsfRw4pGrS76WYj5tnx",
"type": "deposits",
"eventType": "deposit.completed",
"createdAt": "2026-04-28T08:32:50.618Z",
"data": {}
}
```
| Field | Type | Notes |
| ----------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `id` | string (readable ID, `evt_` prefix) | Unique per event. Deduplicate on this field — store it on first successful processing and treat repeats as no-ops. |
| `type` | string | Resource noun: always `"deposits"` for deposit events. |
| `eventType` | string | Dotted action: `"deposit.completed"` or `"deposit.failed"`. |
| `createdAt` | string (RFC 3339, ms, UTC) | When OpenFX created the event. |
| `data` | object | The Deposit resource in its current state. See field reference below. |
## Payload
```json theme={null}
{
"id": "evt_7m4VsfRw4pGrS76WYj5tnx",
"type": "deposits",
"eventType": "deposit.completed",
"createdAt": "2026-04-28T08:32:50.618Z",
"data": {
"object": "deposit",
"id": "dpt_EA9vbVngB76PmMibCiMNPb",
"currency": "USD",
"assetType": "FIAT",
"depositAmount": "1000.00",
"status": "COMPLETED",
"network": null,
"transactionHash": null,
"referenceId": "Deposit from XYZ",
"comments": null,
"memo": null,
"paymentDetails": {
"FEDWIRE": {
"imad": "20260428B1QGC07C001234",
"omad": "20260428L1B7012C003456"
}
},
"createdAt": "2026-04-28T08:30:10.204Z"
}
}
```
| Field | Notes |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `assetType` | `"FIAT"` for bank-rail deposits. |
| `network` | `null` for fiat deposits — there is no chain to read. |
| `paymentDetails` | Rail-specific identifiers keyed by transfer type (e.g. `FEDWIRE` IMAD/OMAD). `null` for deposits without rail metadata. |
| `referenceId` | External reference supplied by the customer, if any. `null` if none was supplied. |
| `depositAmount` | String decimal — e.g. `"1000.00"`. May be negative for late rail reversals (SWIFT MT103 return, SEPA recall, ACH return). |
```json theme={null}
{
"id": "evt_7m4VsfRw4pGrS76WYj5tnx",
"type": "deposits",
"eventType": "deposit.completed",
"createdAt": "2026-04-28T08:32:50.618Z",
"data": {
"object": "deposit",
"id": "dpt_EA9vbVngB76PmMibCiMNPb",
"currency": "USDT",
"assetType": "CRYPTO",
"depositAmount": "10000.00",
"status": "COMPLETED",
"network": "ETHEREUM",
"transactionHash": "0xabc123def4567890abcdef1234567890abcdef1234567890abcdef123456789",
"referenceId": null,
"comments": null,
"memo": null,
"paymentDetails": null,
"createdAt": "2026-04-28T08:30:10.204Z"
}
}
```
| Field | Notes |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `network` | The chain the deposit was observed on (e.g. `ETHEREUM`, `SOLANA`, `TRON`; see [Supported networks](/v3/supported-networks)). Returned in canonical form. |
| `transactionHash` | The on-chain transaction hash. `null` until the deposit is broadcast. |
| `paymentDetails` | `null` for crypto deposits — rail metadata only applies to fiat. |
| `referenceId` | Typically `null` for stablecoin (no rail reference concept). |
| `depositAmount` | String decimal. |
`status` is one of `PENDING`, `COMPLETED`, or `ERROR`. The webhook catalog
ships terminal `deposit.completed` and `deposit.failed` events; the v3 API
surfaces the same record with matching status via [`GET
/v3/fx/deposits`](/v3/api-reference/trade-settlement/list-deposits) — no
normalization needed between webhook and API surfaces.
## Deposit resource fields
| Field | Type | Notes |
| ----------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `object` | string | Always `"deposit"`. |
| `id` | string (readable ID, `dpt_` prefix) | Deposit resource ID. |
| `currency` | string | ISO 4217 currency code or stablecoin ticker. |
| `assetType` | string | Asset class: `"CRYPTO"` for on-chain, `"FIAT"` for bank rails. |
| `depositAmount` | string | Decimal string, e.g. `"1000.00"`. May be negative for late rail reversals. |
| `status` | string | `PENDING` \| `COMPLETED` \| `ERROR`. |
| `network` | string \| null | Settlement network for crypto deposits (canonical form, e.g. `ETHEREUM`); `null` for fiat deposits. |
| `transactionHash` | string \| null | On-chain transaction hash for crypto deposits, `null` otherwise. |
| `referenceId` | string \| null | External reference supplied by the customer, if any. |
| `comments` | string \| null | Free-text comments captured at deposit time. |
| `memo` | string \| null | Optional memo line provided with the deposit. |
| `paymentDetails` | object \| null | Payment-rail-specific identifiers (e.g. FEDWIRE IMAD/OMAD), keyed by transfer type. Present only for fiat deposits with rail metadata; `null` for crypto deposits and any deposit without rail metadata. |
| `createdAt` | string (RFC 3339, ms, UTC) | When the deposit was created. |
## Idempotency on your side
Webhook deliveries can repeat — networks fail, your service restarts, OpenFX retries. The event `id` is unique per event; persist it on first successful processing and treat repeat `id`s as no-ops. Do **not** rely on `data.id` (the deposit resource ID) for dedup — a single deposit can legitimately appear in multiple event deliveries if your handler returned a non-2xx on an earlier attempt.
This handler fragment assumes signature verification has already produced `rawBody` and omits the surrounding asynchronous route plus application-provided `db`, `res`, and `processDeposit` definitions.
```javascript theme={null}
// After signature verification:
const event = JSON.parse(rawBody.toString("utf8"));
if (await db.webhookEvents.exists(event.id)) {
return res.status(200).end(); // already processed; ack so OpenFX stops retrying
}
await processDeposit(event.data);
await db.webhookEvents.insert({ id: event.id, processedAt: new Date() });
res.status(200).end();
```
## Verification
Every event is signed in the `X-OpenFX-Signature` header using HMAC-SHA256 over the signed payload `timestamp + "." + raw_body`. Always verify with a constant-time comparator before reading any payload field. See [Webhook authentication](/v3/webhooks/authentication) for the signing scheme, language-specific verifiers, and rotation steps.
## What's next
Signature verification with constant-time comparators.
The other side of the deposit/withdrawal lifecycle.
How deposits transition from pending to completed.
Stable error codes and the retry triage matrix.