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
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.
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 for subscription management, signature verification, delivery behavior, and processing guidance.