# Events

Product: Account API
Guides follow API reference 0.3.0 and event reference 0.2.0.
Canonical page: https://docs.axiym.io/account-api/webhooks/events

Account API webhooks cover withdrawal, deposit, account, and address book entry
lifecycle events. 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 when you need its complete or current state.

## 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](/account-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`. |

## Account events

| Event               | Meaning                                                              |
| ------------------- | -------------------------------------------------------------------- |
| `account.credited`  | A posted movement credited the account. Carries the movement amount. |
| `account.debited`   | A posted movement debited the account. Carries the movement amount.  |
| `account.activated` | The account became active and available for permitted operations.    |
| `account.suspended` | The account was temporarily unavailable for permitted operations.    |
| `account.closed`    | The account was permanently retired.                                 |

`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 avoid double-counting
deposits and withdrawals 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`. |

## Address book entry events

| Event                   | Meaning                                                            |
| ----------------------- | ------------------------------------------------------------------ |
| `destination.created`   | A new destination was registered and is awaiting review.           |
| `destination.activated` | The address book entry became usable for deposits and withdrawals. |
| `destination.suspended` | The address book entry was temporarily suspended.                  |
| `destination.closed`    | The address book entry was permanently retired.                    |

## Subscription test event

| Event               | Meaning                                                          |
| ------------------- | ---------------------------------------------------------------- |
| `subscription.test` | A test delivery was requested. Its `data` is `{ "test": "OK" }`. |

## Processing guidance

* Verify the webhook signature before processing the payload.
* De-duplicate deliveries by the event `id`.
* Dispatch by event `type` and validate its `data` shape. Use `withdrawalId`,
  `depositId`, `accountId`, or `destinationId` as appropriate, plus `externalReference` where
  present, to correlate it with your records.
* Handle `subscription.test` without a resource lookup. Safely ignore unsupported
  event types; subscriptions can receive events outside this catalogue.
* Treat webhooks as at-least-once delivery. Duplicate events can occur.
* Retrieve current withdrawal state through `GET /withdrawals/{withdrawalId}`,
  deposit state through `GET /deposits/{depositId}`, account state through `GET /accounts/{accountId}`, or address book state
  through `GET /address-book/{destinationId}` when needed.
* Validate resource ownership using your stored identifiers. If you also use
  Client Trade, route its resource events by `clientId`; a missing `clientId`
  alone does not establish organization ownership.
* Confirmation itself starts execution; continue to use the withdrawal resource
  and subsequent lifecycle events to observe the outcome.