Webhooks Overview

Webhooks let Axiym notify your service when Direct Trade API resources change. Use webhooks to track deposits, withdrawals, conversions, address book entries, and posted Axiym account balance movements without continuously polling every resource.

How it works

1. Register an HTTPS endpoint. Create a subscription with POST /webhooks/subscriptions. See Registration and Management.
2. Receive events. Axiym sends an HTTP POST with a JSON event envelope to each active subscription endpoint.
3. Verify the signature. Every delivery is signed with Ed25519. Verify it before trusting the payload. See Verifying Webhook Signatures.
4. Acknowledge delivery. Return a 2xx response 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 event emitted for your company, including event types outside this Direct Trade API reference. Ignore unknown event types safely. Direct Trade API resource event payloads carry no clientId: every event describes a resource your organization owns, even when the operation supports a customer workflow in your system. If your organization also operates the Client Trade API, the same subscriptions receive its client resource events too; those 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: subscription tests and unrelated events can also omit it.

Event catalogue

The Direct Trade API emits deposit, withdrawal, conversion, address-book-entry, and Axiym account-movement events. Address book entries 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 where available.

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:

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. The published contract does not define a source-IP allowlist. Do not rely on fixed addresses; confirm any network restrictions with Axiym for your environment.

Related pages

• Webhook Registration and Management
• Verifying Webhook Signatures
• Events