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.

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

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

Webhook source IPs

If your receiver restricts inbound traffic, allowlist these source addresses:

Signature verification remains required even when source IP filtering is in place.