# Webhooks Overview

Product: Account API
Guides follow API reference 0.3.0 and event reference 0.2.0.
Canonical page: https://docs.axiym.io/account-api/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

1. **Register an HTTPS endpoint.** Create a subscription with
   `POST /webhooks/subscriptions`. See
   [Registration and Management](/account-api/webhooks/registration-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](/account-api/webhooks/verifying-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. 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](/account-api/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.

## Related pages

* [Webhook Registration and Management](/account-api/webhooks/registration-management)
* [Verifying Webhook Signatures](/account-api/webhooks/verifying-signatures)
* [Events](/account-api/webhooks/events)