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.

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

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.