Notifications and webhooks
Many Account API operations are asynchronous. A deposit may take time to arrive, an 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
Event
A record that something changed, such as a deposit completing or an external account 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, external account, 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
Account 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: changes in conversion status;
- External accounts: registration, activation, suspension, or closure; and
- Withdrawals: changes in withdrawal status.
For example, an external account becoming active means it has passed review and is now whitelisted for use. A deposit completing means its Axiym account has been credited.
The exact event names and payloads are documented in the Events reference.
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 combines:
- 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.
The same event may be delivered more than once. Your integration should handle repeated deliveries without repeating the resulting action.
An event describes a change at a point in time. The resource may have changed again by the time the notification arrives. API reads provide its current state and complete details.
Next step
When you are ready to implement the receiver, use the Webhooks section for subscription management, signature verification, delivery behavior, and processing guidance.