Notifications and webhooks

Many Direct 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

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

Direct 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: 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.

Organization-owned events carry no clientId

Every Direct Trade API event describes a resource your organization owns, so the payloads carry no clientId. This remains true when the underlying operation supports a customer workflow: customer attribution stays in your system. If you also operate the Client Trade API, its client resource events carry a clientId. Validate the event type and payload shape before routing it, and use your stored resource ownership mapping. A missing clientId alone does not prove organization ownership: test deliveries and unrelated events can also omit it. Never infer ownership 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. For an unconfirmed conversion, use the retained create response until confirmation makes resource reads available.

Next step

When you are ready to implement the receiver, use the Webhooks section for subscription management, signature verification, delivery behavior, and processing guidance.