Webhook events

OMS sends 26 webhook event types across 9 resources. Subscribe with POST /webhooks, passing a url and the subscriptions you want. To build the endpoint that receives them, see Receiving webhooks.

Subscriptions

Selector	Covers
`*`	Every event type in this catalog.
An event `type`, such as `transaction.statusChanged`	That event type only.

A subscription that names a type not in this catalog receives nothing.

Envelope

Every event has the same six fields.

Field	Type	Description
`id`	string	The event ID: `evt_` followed by 26 base32 characters. Unique per event and the same on every retry. Do not parse it as a UUID.
`idempotencyKey`	string	A UUID that is the same on every emission of one change, so a repeat that arrives with a new `id` can still be recognized.
`type`	string	`<resource>.created`, `<resource>.statusChanged`, or `<resource>.updated`.
`createdAt`	timestamp	When OMS recorded the change, in UTC with three fractional digits. Strictly increasing per resource. Never the send time.
`schema`	string	`v1`. An empty string marks an event written before the current format.
`data`	object	The resource and what changed. See below.

data holds:

Field	Present on	Description
`resource`	Every event	The resource as its `GET` endpoint returns it at that moment, with empty lists left out.
`previousStatus`	`*.statusChanged`	The status the resource changed from. Left out the first time OMS sees the resource.
`changedFields`	`*.updated`	The names of the fields that changed.

{
  "id": "evt_01m3vwfty8f9a96p8vzvc8yc5n",
  "idempotencyKey": "9ab1f992-0f66-5ecf-be2d-dc7efa707933",
  "type": "transaction.statusChanged",
  "createdAt": "2026-10-01T14:04:29.512Z",
  "schema": "v1",
  "data": {
    "resource": {
      "id": "txn_01mqyagza72777t0paefp51exd",
      "status": "processing",
      "subStatus": "processing.awaitingFiatOut",
      "customer": { "id": "cst_01mx4k2r8ve1q0g7d6hb3c5n9p" },
      "precursor": { "type": "depositAddress", "id": "da_01mqvxp81c2xq4qftg100fdsjr" },
      "source": {
        "type": "walletExternal",
        "asset": "usdc",
        "network": "ethereum",
        "details": { "address": "0x3f1c9a7e52b04d8e6a1f2c7b9d0e4a6b8c2d5e71" }
      },
      "destination": {
        "type": "bankUs",
        "id": "ext_01mx4m0c7t2w9b6q3d8f1e5k4r",
        "asset": "usd",
        "details": { "accountNumberLast4": "7845", "accountType": "checking", "holderName": "Jane Doe" }
      },
      "pricing": {
        "source": { "amount": "2500.000000", "asset": "usdc" },
        "destination": { "amount": "2492.50", "asset": "usd" },
        "exchangeRate": "1.000000",
        "fees": [{ "type": "oms", "side": "destination", "asset": "usd", "amount": "7.50" }]
      },
      "transfers": [
        { "id": "trf_01mqyah0b3c4d5e6f7g8h9j0k1", "role": "deposit", "rail": "blockchain", "attempt": 1 }
      ],
      "createdAt": "2026-10-01T14:03:10.205Z",
      "updatedAt": "2026-10-01T14:04:29.512Z"
    },
    "previousStatus": "processing"
  }
}

A field that does not apply, or has no value yet, is left out rather than sent as null. Status, sub-status, and event-type lists can grow without a version bump: ignore a type you do not handle, and fall back to the part of a sub-status before the dot.

Event types

Each resource sends created once, statusChanged on every status change, and updated for any other visible change. Deleting or closing a resource is a status change. A resource that existed before you subscribed has no created event, so treat the first event you see for an ID as its creation.

Resource	Events	Statuses
`customer`	`customer.created`, `customer.statusChanged`, `customer.updated`	`pending`, `actionRequired`, `active`, `rejected`, `offboarded`
`externalAccount`	`externalAccount.created`, `externalAccount.statusChanged`, `externalAccount.updated`	`pending`, `active`, `rejected`, `invalid`, `deleted`, `failed`
`counterparty`	`counterparty.created`, `counterparty.statusChanged`, `counterparty.updated`	`active`, `rejected`, `deleted`
`customerWallet`	`customerWallet.created`, `customerWallet.statusChanged`, `customerWallet.updated`	`pending`, `active`, `frozen`, `suspended`, `closed`
`depositAddress`	`depositAddress.created`, `depositAddress.statusChanged`, `depositAddress.updated`	`pending`, `active`, `frozen`, `closed`, `failed`, `inactiveActionRequired`
`virtualAccount`	`virtualAccount.created`, `virtualAccount.statusChanged`, `virtualAccount.updated`	`pending`, `active`, `frozen`, `closed`, `failed`, `inactiveActionRequired`, `deleting`, `deleted`
`cashIn`	`cashIn.created`, `cashIn.statusChanged`, `cashIn.updated`	`pending`, `processing`, `completed`, `failed`, `expired`
`transaction`	`transaction.created`, `transaction.statusChanged`	`processing`, `awaitingAction`, `completed`, `failed`, each with a `subStatus`
`transfer`	`transfer.created`, `transfer.statusChanged`, `transfer.updated`	`initiated`, `pending`, `settled`, `failed`, `returned`

Resource notes

transaction: a change of subStatus alone also sends transaction.statusChanged, with previousStatus equal to status. There is no transaction.updated. Sub-statuses are listed in the transaction lifecycle.
transfer: one movement of money on one rail. A transaction is made of a deposit transfer, a payout transfer, and a refund transfer when money goes back to the sender. A transfer that moves through several statuses at once sends one statusChanged per status. transfer.updated reports late details such as a transaction hash in tracking.
customer: sent a short delay after the change. data.resource is the GET /customers/{customerId} body without balances or empty lists. A customer OMS sees for the first time is announced pending in customer.created, then moved by customer.statusChanged with previousStatus: "pending", even if it was already active. Endorsement changes arrive as customer.updated with endorsements in changedFields.
customerWallet: created carries pending with no address; statusChanged to active carries the address. updated covers label, metadata, and the first address.
depositAddress: created carries pending. changedFields on updated is a subset of destination, payout, returnDestination, label, metadata, and depositInstructions.
virtualAccount: created carries pending. changedFields on updated is a subset of depositInstructions, destination, label, metadata, payout, returnDestination, and returnPayout. A delete sends statusChanged into deleting and again on to deleted.
cashIn: refreshing the cash-in code sends cashIn.updated with changedFields: ["depositInstructions"].
externalAccount: a move to invalid (for example after a bank return) always sends statusChanged.

Deposits into deposit addresses and virtual accounts, and their payouts, are reported through transaction.* and transfer.*. There are no per-rail deposit or payout events.

Never delivered

transaction.cryptoToCrypto.underReview, transaction.cryptoToFiat.underReview, and transaction.fiatToCrypto.underReview exist for compliance only. They are never delivered and cannot be subscribed to. A transaction under review reads processing.underReview, announced through transaction.statusChanged.

Delivery

Each delivery is an HTTPS POST of the envelope, signed in a Webhook-Signature header: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 under your signing key of <t>.<raw request body>. Reject a t more than 300 seconds from your clock. The timestamp and signature are regenerated on every attempt.
A 2xx acknowledges. Anything else, a timeout (the webhook’s timeoutMs, default 5000, maximum 10000), or a network error is retried 10 times over about 3 days.
Delivery is at-least-once, in parallel, and unordered. Deduplicate on id and idempotencyKey; order by createdAt per resource.
An endpoint failing continuously for about 72 hours is suspended. Re-enable it with POST /webhooks/{webhookId}/enable.
Delivery history is kept for 30 days. GET /webhooks/{webhookId}/deliveries lists it (filters status, eventId, test, createdAfter, createdBefore), and each record nests the body sent under event. POST /webhooks/{webhookId}/deliveries/retry sends deliveries again. There is no GET /events.

Attempts so far	0	1	2	3	4	5	6	7	8	9
Delay before the next	0s	5s	10s	30s	1m	10m	1h	6h	1d	2d

Manage endpoints with POST/GET /webhooks, GET/PATCH/DELETE /webhooks/{webhookId}, and POST /webhooks/{webhookId}/enable, /disable, /rotate-key, and /test. See the API reference.

Overview

Move money

Routes

External Payment Methods

Platform

Read onchain data

Subscriptions

Envelope

Event types

Resource notes

Never delivered

Delivery

​Subscriptions

​Envelope

​Event types

​Resource notes

​Never delivered

​Delivery

Subscriptions

Envelope

Event types

Resource notes

Never delivered

Delivery