Notifications and webhooks

Many Trade API operations are asynchronous. A deposit may take time to arrive, a registered external account 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

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. If your decision requires the resource's complete or latest state, retrieve that resource from the Trade API before continuing.

An event is therefore a signal that something changed, not a replacement for the resource itself.

What you can be notified about

Trade API events report changes across the main resource lifecycles:

• Axiym accounts: posted balance movements and account status changes;
• Deposits: incoming payments being detected, held, completed, canceled, or rejected;
• Conversions: conversions being created, completed, or canceled;
• Registered external accounts: owned bank accounts or wallets being registered, activated, suspended, or closed; and
• Withdrawals: withdrawals being created, held, completed, canceled, or rejected.

Registered external-account events retain the destination.* names used by the API contract. For example, destination.activated means that a registered external account became active; it is not a separate destination-only resource.

The exact event names and payloads are documented in the Events reference.

Route notifications to the 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.