Webhook Events

Each object in the platform has its own lifecycle and its status changes as it transitions between states.

Whenever one such transition occurs, a webhook event is fired.

Setup

Currently, you can nominate a webhook destination by contacting support.

In order to create a destination, please provide a HTTPS URL and your desired authentication method.

Authentication

The platform support the following authentication styles when sending webhooks.

Authentication	Description	Info needed
SHA-256 signature	HTTP header that contains SHA-256 signature of payload, signed by a shared secret	Signing secret Header name
API key	API key provided in HTTP header or URL query	Header or query name API key
Basic auth	Username and password, encoded in `Authorization: Basic xxxx` header	Username Password

When requesting webhook access, ensure you provide the "Info needed" details to MoveUSD support.

Retries

When consuming webhooks, it is the best practice to accept the events as they are, return a successful response and handle any errors or retries within your own platform.

If you choose to propagate the error back to the webhook sender, the webhook request will be retried every hour up to 5 times, regardless of the type of the error. This is not customisable and may cause duplicates within your system. As such, it is recommended to rely on your own retry mechanisms instead.

Payload

All webhook events have a consistent JSON payload.

{
  "event": "<event code>",
  "createdAt": "<ISO timestamp of when the event was generated>",
  "customerId": "<Your customer ID>",
  "data": {
    "id": "<ID of the object that has been updated>",
    "status": "<The new status of the object>"
  }
}

If the event is relevant to an Identity or Organization, additional fields are available at the root of the structure: identityId and identityReferenceId (or organizationId and organizationReferenceId).

Some events may include additional fields in data section. These have been documented in the next section per event.

That said, most events will include only id and status. The expected integration pattern is to perform a GET operation on the given resource to get the latest data for that resource, when a new event arrives. This is to protect consumers from out-of-order delivery issues and they are always working with the latest information about an object.

Events

The following is the exhaustive list of events that you may receive.

`event`	GET operation	Notes
`account.ledgerAccount.created`	Get a ledger account details	No `status` field
`card.cardTransaction.statusUpdated`	N/A
`customer.terms.statusUpdated`	N/A	Example of `data` field: `[{"type":"MOVEUSD_TERMS_OF_USE","status":"ACCEPTED"},{"type":"COOKIES_POLICY","status":"ACCEPTED"},{"type":"ESIGN_POLICY","status":"ACCEPTED"},{"type":"PRIVACY_POLICY","status":"ACCEPTED"}]`
`deposit.cashRequest.statusUpdated`	Get Cash Deposit Request	Example of `data` field: `{"status":"EXPIRED","cashDepositRequestId":"cshdprq_nloJZiL5DWaxkdx3joPsV","cashDepositRequestReference":"ad4e0289-6b55-4bcd-a31c-50b8ec418b9c","cashDepositTransactionReference":"180f02ad-abe3-4a88-b190-ea62807429ee","amount":{"currency":"MOVEUSD","amount":20}}`
`deposit.direct.statusUpdated`	N/A
`deposit.deposit.statusUpdated`	Get Deposit	Example of `data` field: `{"status":"PROCESSING","type":"US_BANK_ACH","depositId":"dp_AM6nDeazjlh9kq7xuoqEl","depositReference":"063b5d0e-668f-4fae-87fd-8e81b6b5e9b5"}`
`identity.identity.registered`	Get an identity	No `id` field; Already provided at root level via `identityId`.
`identity.identity.statusUpdated`	Get an identity	No `id` field; Already provided at root level via `identityId`.
`identity.verification.statusUpdated`	N/A	Examples of `data` field: `{"type": "AML", "status": "APPROVED"}` `{"type: "IDENITY_DOCUMENT", "status": "DECLINED"}` Refer to `*Verification` fields in Get an identity for possible values for `status.`.
`organization.organization.created`	Get Organization	No `id` field; Already provided at root level via `organizationId`.
`organization.organization.statusUpdated`	Get Organization	No `id` field; Already provided at root level via `organizationId`.
`paymentInstrument.afBank.statusUpdated`	Get Payment Instrument
`paymentInstrument.afMomo.statusUpdated`	Get Payment Instrument
`paymentInstrument.mxClabe.statusUpdated`	Get Payment Instrument
`paymentInstrument.networkWallet.statusUpdated`	Get Payment Instrument
`paymentInstrument.swiftWire.statusUpdated`	Get Payment Instrument
`paymentInstrument.usAch.statusUpdated`	Get Payment Instrument
`paymentInstrument.usWire.statusUpdated`	Get Payment Instrument
`paymentInstrument.wallet.statusUpdated`	Get Payment Instrument
`redemption.transfer.statusUpdated`	Get an existing transfer by ID
`reward.reward.created`	Get Reward	Example of `data` field: `{"id":"rew_XvMToLmvLm74ve0GVTBOb","transactionType":"DEBIT","amount":{"amount":50,"currency":"MOVEUSD"},"phone":"+123456789","idempotencyKey":"dc5a2616-7711-43dc-b376-4b7d1f4b3c5e","category":"Rewards","note":"Good one!","createdAt":"2025-10-21T20:14:29.771Z"}`
`swap.swap.statusUpdated`	Get Swap
`withdrawal.withdrawal.statusUpdated`	Get Withdrawal

Please refer to the provided GET operation for the possible values for status.