Webhooks Overview
Webhooks let Axiym notify your service when a withdrawal or deposit changes state. Use webhooks to keep your system in sync as a withdrawal or deposit is created and as it moves to held, completed, canceled, or rejected. Confirmation starts withdrawal execution; fetch the withdrawal after confirming it when current state matters.
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. Handle events by type and payload shape, including account, address book, and subscription-test events. Safely ignore unsupported types: the endpoint may receive notifications outside this Account API catalogue.
Event catalogue
The Events reference includes withdrawal and deposit lifecycle events, Axiym account events, and address-book-entry events. See Events for exact names, envelopes, and payload schemas.
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.
If your receiver restricts inbound traffic, confirm the applicable network requirements with Axiym. The published contract does not guarantee fixed source IP addresses.