# Events

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

Account API webhooks cover withdrawals, deposits, conversions, registered
external accounts, and Axiym accounts. Each event is delivered as a webhook
envelope with a `type` and a compact `data` payload.

Event payloads identify the affected resource and describe the change so you
can correlate it with your records. Fetch the corresponding resource from the
Account 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](/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`. |

## 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.
A `TRANSFER` movement is a transfer of a client's balance to your settlement
account with the PNSL API [`POST /clients/{clientId}/transfers`](/pnsl-api/api-reference/2.0.0/receivables/createClientTransfer):
`account.credited` on your account and `account.debited` on the client's.

## 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 `destination.*` events describe the review and availability of external
bank accounts and wallets registered in your address book. Once whitelisted
with status `ACTIVE`, an external account can fund deposits and receive
withdrawals.

| Event                   | Meaning                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------ |
| `destination.created`   | An external account was registered and is awaiting due diligence and compliance checks.          |
| `destination.activated` | The external account was approved and became `ACTIVE`, whitelisted for deposits and withdrawals. |
| `destination.suspended` | The external account became temporarily unavailable for deposits and withdrawals.                |
| `destination.closed`    | The external account was permanently retired.                                                    |

See [Address book and external accounts](/account-api/concepts/address-book)
for whitelisting and the 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 routing it. Ignore unknown
  event types safely.
* Handle duplicate deliveries without repeating the resulting action.
* Fetch the corresponding resource from the API if ordering matters or if you
  need the latest state before continuing.