# Events Product: Direct Trade API Guides follow API reference 0.1.0 and event reference 0.1.0. Canonical page: https://docs.axiym.io/direct-trade-api/webhooks/events Direct Trade API webhooks cover 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. Each Direct Trade resource event describes a resource your organization owns, so the payloads carry no `clientId`, including when the operation supports a customer workflow. Fetch the corresponding resource from the Direct Trade API when you need its complete or latest state. An unconfirmed conversion is not available through reads; use the retained create response until 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](/direct-trade-api/events) — it is the source of truth for webhook payloads. ## 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 /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`. | ## Subscription test event | Event | Meaning | | ------------------- | ----------------------------------------------------------------------------- | | `subscription.test` | Sent only when you request a test delivery. Its `data` is `{ "test": "OK" }`. | ## 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](/direct-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. * Validate the event type and payload shape before resolving resource ownership. If your organization also operates the Client Trade API, route its resource events using `clientId`. For Direct Trade resource events, use your stored ownership mapping. Missing `clientId` alone does not establish ownership; subscription tests and unrelated events can also omit it. * 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.