Deposit webhooks

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.

{
  "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

Fiat (wire / ACH / SEPA)
Stablecoin (USDC / USDT / EURC)

{
  "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).

{
  "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). 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 — 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 ids 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.

// 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 for the signing scheme, language-specific verifiers, and rotation steps.

What’s next

Webhook authentication

Signature verification with constant-time comparators.

Withdrawal webhooks

The other side of the deposit/withdrawal lifecycle.

Deposit lifecycle

How deposits transition from pending to completed.

Errors

Stable error codes and the retry triage matrix.

Get Started

Platform basics

FX

Operations

Glossary

Webhooks

Deposit webhooks

Event envelope

Payload

Deposit resource fields

Idempotency on your side

Verification

What’s next

Webhook authentication

Withdrawal webhooks

Deposit lifecycle

Errors

​Event envelope

​Payload

​Deposit resource fields

​Idempotency on your side

​Verification

​What’s next

Webhook authentication

Withdrawal webhooks

Deposit lifecycle

Errors

Event envelope

Payload

Deposit resource fields

Idempotency on your side

Verification

What’s next