# Events Product: Client Trade API Guides follow API reference 0.3.0 and event reference 0.2.0. Canonical page: https://docs.axiym.io/trade-api/webhooks/events Client Trade API webhooks cover client onboarding and availability, withdrawals, deposits, conversions, address book entries, and posted Axiym account balance movements. Each event is delivered as a webhook envelope with a `type` and a compact `data` payload. Webhooks are notifications, not state transfer: the payload carries just enough to route the event and correlate it with your records. Fetch the corresponding resource from the Client Trade API when you need its complete or latest state. For an unconfirmed conversion, use the retained create response; conversion reads are available only after confirmation. ## Event envelope | Field | Description | | ----------- | ------------------------------------------------------------- | | `id` | Unique webhook event identifier. Use this for de-duplication. | | `timestamp` | Time when Axiym created the event. | | `type` | Event name. | | `data` | Compact event payload. | The exact `data` schema and a full payload example for every event are in the [Events reference](/trade-api/events) — it is the source of truth for webhook payloads. ## Client events | Event | Meaning | | ---------------------------- | ----------------------------------------------------------------------------------------------- | | `client.created` | Axiym created a client record for the partnership. | | `client.updated` | Axiym updated a client record. A disabled or archived update also emits `client.disabled`. | | `client.onboarding-finished` | **Deprecated.** Legacy activation event, emitted alongside `client.activated` during migration. | | `client.activated` | A client became available for Client Trade API operations, initially or after being disabled. | | `client.disabled` | A client is no longer available for new Client Trade API operations. | Use `client.activated` as the asynchronous signal that a client became available, including after reactivation. Fetch `GET /clients/{clientId}` to check current availability and start business operations only when its status is `ACTIVE`. Use `GET /onboardings/{clientId}` for the onboarding outcome and any available rejection reason. ## Withdrawal events | Event | Meaning | | ---------------------- | ---------------------------------------------------------------------- | | `withdrawal.created` | A withdrawal was confirmed and accepted for execution. | | `withdrawal.held` | Withdrawal processing is temporarily on hold. | | `withdrawal.completed` | A withdrawal completed successfully. | | `withdrawal.canceled` | A withdrawal was canceled before completion. Carries `reasonCode`. | | `withdrawal.rejected` | A withdrawal was rejected and will not complete. Carries `reasonCode`. | ## Axiym account events | Event | Meaning | | ------------------- | -------------------------------------------------------------------------- | | `account.credited` | A posted movement credited the Axiym account. Carries the movement amount. | | `account.debited` | A posted movement debited the Axiym account. Carries the movement amount. | | `account.activated` | The Axiym account became active, initially or after a suspension. | | `account.suspended` | The Axiym account was suspended. | | `account.closed` | The Axiym account was closed. | `account.credited` / `account.debited` describe immutable posted movements, so the amount is part of the event; the current balance is not — fetch it via `GET /clients/{clientId}/accounts/{accountId}`. Movements linked to an API resource carry `relatedResourceType` / `relatedResourceId` so you can correlate them with the deposit, conversion, or withdrawal you already track. A `PAYOUT` movement originates from the Payment API; retrieve the payout there. ## Deposit events | Event | Meaning | | ------------------- | ----------------------------------------------------------------------------------- | | `deposit.created` | An incoming payment was detected and is awaiting crediting. | | `deposit.held` | Deposit processing is temporarily on hold. | | `deposit.completed` | A deposit completed and credited the receiving Axiym account. | | `deposit.canceled` | A deposit was canceled before the Axiym account was credited. Carries `reasonCode`. | | `deposit.rejected` | A deposit was rejected and will not credit the Axiym account. Carries `reasonCode`. | ## Conversion events | Event | Meaning | | ---------------------- | ------------------------------------------------------------------------------------------------------------ | | `conversion.created` | A conversion was confirmed and execution has begun. | | `conversion.completed` | A conversion completed; the sell-side Axiym account was debited and the buy-side Axiym account was credited. | | `conversion.canceled` | A conversion was canceled, expired, or could not complete. Carries `reasonCode`. | ## Address book entry events The API contract retains the `destination.*` event names for address book entries. These events describe the lifecycle of the owned bank account or wallet used as a deposit source and withdrawal recipient; they do not represent a separate destination-only resource. | Event | Meaning | | ----------------------- | ----------------------------------------------------------------------------------------------- | | `destination.created` | An address book entry was created and is awaiting review. | | `destination.activated` | The address book entry became available as a permitted deposit source and withdrawal recipient. | | `destination.suspended` | The address book entry became temporarily unavailable for deposits and withdrawals. | | `destination.closed` | The address book entry was permanently retired. | See [Address Book](/trade-api/concepts/address-book) for the ownership model and account lifecycle. ## Processing guidance * Verify the webhook signature before processing the payload. * De-duplicate deliveries by the event `id`. * Use the resource identifier and `externalReference` where present to correlate the event with your records. * Dispatch by event `type` first. Require `clientId` for Client Trade resource events and use it with your stored resource ownership mapping to route them. The `subscription.test` payload is `{ "test": "OK" }` and has no `clientId`; other product events may also use a different shape. Handle test deliveries separately and ignore unknown event types safely. * Treat webhooks as at-least-once delivery. Duplicate events can occur. * Fetch the corresponding resource from the API if ordering matters or if you need the latest state before continuing.