Webhooks Overview
Webhooks let Axiym notify your service when Trade API resources change. Use webhooks to track client onboarding, deposits, withdrawals, conversions, registered external accounts, and posted Axiym account balance movements without continuously polling every resource.
How it works
- Register an HTTPS endpoint. Create a subscription with
POST /webhooks/subscriptions. See Registration and Management. - Receive events. Axiym sends an HTTP
POSTwith a JSON event envelope to each active subscription endpoint. - Verify the signature. Every delivery is signed with Ed25519. Verify it before trusting the payload. See Verifying Webhook Signatures.
- Acknowledge delivery. Return a
2xxresponse after your system has safely persisted or queued the event.
Webhook subscriptions are endpoint-level. The current API does not expose per-event subscription filters. An active subscription receives every Trade API event available for clients represented by your partnership.
Event catalogue
The Trade API emits client, deposit, withdrawal, conversion, registered
external-account, and Axiym account-movement events. A
client.onboarding-finished event is a deprecated legacy activation event;
use client.activated for new integrations. Registered external accounts
retain the destination.* event-name prefix used by the contract. See
Events for event names, the shared webhook
envelope, and the fields delivered in data.
Delivery and retries
Axiym treats any 2xx response as accepted. If the endpoint returns a non-2xx
status or the connection fails, Axiym retries the delivery.
- Up to 4 attempts per event: the initial delivery plus 3 retries.
- Exponential backoff between retries: about 1 second, then 2 seconds, then 4 seconds.
- After the final attempt, the event is not delivered again automatically.
Webhook delivery is at-least-once. Your receiver must be idempotent and
de-duplicate events by id. Do not rely on webhook delivery order as the only
source of state; fetch the resource from the API when you need the latest
authoritative state.
Keep handlers fast. A common pattern is to verify the signature, persist or
enqueue the event, return 2xx, and process the business logic asynchronously.
Security
Webhook deliveries include these headers:
| Header | Description |
|---|---|
X-Signature | Base64 Ed25519 signature of the raw request body. |
X-Key-Id | Public key identifier used to verify the signature. |
X-Algorithm | Signature algorithm. Expected value: Ed25519. |
Use GET /webhooks/public-keys/{publicKeyId} to retrieve the public key for
the X-Key-Id value. Signature verification must use the raw HTTP request body,
before JSON parsing or re-serialization.
Source IP addresses. Axiym delivers webhooks from fixed Cloud NAT egress IPs. If your receiver restricts inbound traffic, allowlist them:
| Environment | Source IP |
|---|---|
| Sandbox | 34.65.12.190 |
| Production | 34.65.60.223 |
These addresses are stable; we'll notify you in advance before they change.