# Notifications and webhooks

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/concepts/notifications-and-webhooks

Many Client Trade API operations are asynchronous. A deposit may take time to arrive,
an address book entry must pass review before it can be used, and a
withdrawal can move through several states before it completes.

You should not have to continuously request each resource to discover these
changes. Instead, Axiym can notify your system by sending **events** to a
webhook endpoint that you register.

## Key concepts

Event

A record that something changed, such as a deposit completing or a
address book entry becoming active.

Webhook

The HTTPS delivery that carries an event from Axiym to your system.

Subscription

The registration that tells Axiym which webhook endpoint should receive
events.

Resource

The authoritative Axiym account, deposit, conversion, address book
entry, or withdrawal represented by the event.

## How notifications fit into your workflow



```mermaid
flowchart TD
  operation["A resource changes"] --> event["Axiym creates an event"]
  event --> webhook["Webhook delivers the event"]
  webhook --> integration["Your system reacts"]
  integration -.->|when current details are needed| api["Fetch the resource from the API"]

  class operation,api resourceNode
  class event eventNode
  class webhook webhookNode
  class integration integrationNode
```



Use the notification to trigger your workflow—for example, to update an order,
release a dependent action, inform a user, or begin reconciliation.

## What you can be notified about

Client Trade API events report changes across the main resource lifecycles:

* **Clients:** client records being created or updated, and clients being
  activated or disabled;
* **Axiym accounts:** posted balance movements and account status changes;
* **Deposits:** incoming payments being detected, held, completed, canceled,
  or rejected;
* **Conversions:** quotes being created, conversions completing, or being
  canceled;
* **Address book entries:** owned bank accounts or wallets being
  registered, activated, suspended, or closed; and
* **Withdrawals:** withdrawals being created, held, completed, canceled, or
  rejected.

The `conversion.created` event is emitted when a quote is created and awaits
confirmation. Execution begins only after confirmation. Keep the create
response: an unconfirmed conversion is not available through conversion reads.

Address book entry events retain the `destination.*` names used by
the API contract. For example, `destination.activated` means that an address book
entry became active; it is not a separate destination-only resource.
`destination.closed` signals that the entry has been permanently retired and
can no longer be used for deposits or withdrawals.

The exact event names and payloads are documented in the
[Events reference](/trade-api/events).

## Route notifications to the client

Client Trade API resource events include `clientId`. Use it together with the resource
identifier to route the notification. Webhook subscriptions belong to the
partnership. Never infer the client from an account number, wallet address, or
other payment detail.

## Webhooks and API reads work together

Webhooks reduce the need for constant polling, but they do not remove the need
for API reads. A robust integration uses both:

* **Webhooks** for timely notification that a change occurred;
* **API reads** for the authoritative current state and complete resource
  details; and
* **Periodic reconciliation** to recover from anything your system failed to
  process.

Process an event as a notification about a resource, not as proof that the
resource still has the same state when your system handles it. Fetch the
current resource before taking an action that depends on its latest status.

## Next step

When you are ready to implement the receiver, use the
[Webhooks section](/trade-api/webhooks/overview) for subscription management,
signature verification, delivery behavior, and processing guidance.