# Webhooks Overview

Product: Account API
Guides follow API reference 0.1.0 and event reference 0.1.0.
Canonical page: https://docs.sandbox.axiym.io/account-api/webhooks/overview

Webhooks let Axiym notify your service when Account API resources
change. Use webhooks to track deposits, withdrawals, conversions, registered
external accounts, 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](/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. An active subscription receives every event
emitted for your organization, including event types outside this Account API
reference. Ignore unknown event types safely. Validate the event type and
payload shape before routing it, and correlate resource identifiers with
your records.

## Event catalogue

The Account API emits events for deposits, withdrawals, conversions, registered
external accounts, and Axiym accounts. External-account events use the
`destination.*` prefix and describe their review and availability.
See [Events](/account-api/webhooks/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.

Deliveries can repeat or be missed if all attempts fail. 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:

| 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.** 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](/account-api/webhooks/registration-management)
* [Verifying Webhook Signatures](/account-api/webhooks/verifying-signatures)
* [Events](/account-api/webhooks/events)