Webhooks Overview
Webhooks let Axiym notify your service when a withdrawal changes state. Use webhooks to keep your system in sync after a withdrawal has been created or moves to held, completed, canceled, or rejected.
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.
Event catalogue
The Events reference includes withdrawal lifecycle events, Axiym account events, and whitelisted-own-account 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.
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.