# Webhooks overview

Receive signed notifications when payout resources change.

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

Webhooks let Axiym notify your service as payouts move through validation,
settlement, execution, and their final outcome.

## How it works

1. Register an HTTPS endpoint with `POST /webhooks/subscriptions`.
2. Axiym sends an HTTP `POST` containing a JSON event envelope.
3. Verify the Ed25519 signature against the raw request body.
4. Persist or queue the event and return a `2xx` response.
5. Fetch the payout when your next action depends on authoritative current
   state.

Subscriptions apply to the endpoint as a whole. The API does not expose
per-event filters. An active subscription receives every event emitted for the
partnership, including event types outside this Payment API reference. Ignore
unknown event types safely.

## Delivery and retries

Axiym treats any `2xx` response as accepted. If the connection fails or the
endpoint returns another status, Axiym retries the delivery.

* Up to 4 attempts: the initial delivery plus 3 retries.
* Backoff of about 1 second, then 2 seconds, then 4 seconds.
* No automatic delivery after the final attempt.

Delivery is at-least-once. De-duplicate by event `id`, do not depend on event
order, and keep the handler fast. A common pattern is verify, persist or queue,
acknowledge, then process asynchronously.

## Security headers

| Header        | Description                                         |
| ------------- | --------------------------------------------------- |
| `X-Signature` | Base64 Ed25519 signature of the raw request body.   |
| `X-Key-Id`    | Identifier of the public key used for verification. |
| `X-Algorithm` | Signature algorithm. Expected value: `Ed25519`.     |

Retrieve unfamiliar keys with
`GET /webhooks/public-keys/{publicKeyId}` and cache them by ID.

## Webhook source IPs

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. Signature verification remains required regardless of network
filtering.