Webhook Registration and Management

Create a webhook subscription to receive outbound event notifications from Axiym. A subscription points to one HTTPS endpoint. Axiym sends Trade API webhook events to each active subscription.

The Trade API event catalogue covers deposits, withdrawals, conversions, registered external accounts, and posted Axiym account balance movements. Registered external-account events retain the destination.* names used by the contract. See Events for the event names and payload shapes.

Endpoint requirements

Your webhook receiver must:

• use HTTPS;
• be reachable by Axiym;
• accept HTTP POST requests with Content-Type: application/json;
• return a 2xx response only after the event has been safely persisted or queued;
• handle duplicate deliveries by de-duplicating on the webhook event id;
• verify webhook signatures before processing the payload.

If your receiver restricts inbound traffic, allowlist the Axiym webhook source IPs listed in Webhooks Overview.

Create a subscription

Use POST /webhooks/subscriptions to register an endpoint.

POST /webhooks/subscriptions HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json
X-Request-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
Idempotency-Key: 0e44f9a0-89d1-40b3-9d3f-d2d76d8b1f24

{
  "endpoint": "https://api.acme.example/webhooks"
}

The API returns 201 Created with a Subscription object.

{
  "subscriptionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "endpoint": "https://api.acme.example/webhooks"
}

endpoint is required and must be a URL. The endpoint must be publicly reachable, use HTTPS, and respond with a 2xx status to webhook POST requests.

Idempotency-Key is accepted on subscription creation. Include it when retrying the same create request.

List subscriptions

Use GET /webhooks/subscriptions to list active webhook subscriptions.

GET /webhooks/subscriptions?first=20 HTTP/1.1
Authorization: Bearer <access_token>
X-Request-Id: 7d1d0b4a-1c84-4e5a-96c8-5f9055c3a86d

The response is paginated.

{
  "nodes": [
    {
      "subscriptionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "endpoint": "https://api.acme.example/webhooks"
    }
  ],
  "pageInfo": {
    "hasNextPage": false
  }
}

Use first to set the page size and after with the previous response's pageInfo.endCursor to request the next page.

Test a subscription

Use POST /webhooks/subscriptions/{subscriptionId}/tests to send a test delivery to one subscription endpoint.

POST /webhooks/subscriptions/3fa85f64-5717-4562-b3fc-2c963f66afa6/tests HTTP/1.1
Authorization: Bearer <access_token>
X-Request-Id: c9c4950b-ded6-4f25-96f5-8be5b7a8378f
Idempotency-Key: 2c0fe60f-f70f-43ef-95c0-0860de38b950

The API returns 201 Created when the test request is accepted.

{
  "status": "OK"
}

Your receiver should handle the test delivery the same way it handles production webhooks: verify the signature, persist or queue the event, and return 2xx.

Disable a subscription

Use DELETE /webhooks/subscriptions/{subscriptionId} when an endpoint should no longer receive events.

DELETE /webhooks/subscriptions/3fa85f64-5717-4562-b3fc-2c963f66afa6 HTTP/1.1
Authorization: Bearer <access_token>
X-Request-Id: 1674f1e8-9d4a-44cd-9fb8-31d98672a6c1

The API returns 200 OK with the disabled subscription.

{
  "subscriptionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "endpoint": "https://api.acme.example/webhooks"
}

Disabled subscriptions are not returned by the list endpoint and do not receive new webhook deliveries.

Signature public keys

Incoming webhook deliveries include an X-Key-Id header. Use GET /webhooks/public-keys/{publicKeyId} to retrieve the corresponding public key before verifying the webhook signature.

GET /webhooks/public-keys/3fa85f64-5717-4562-b3fc-2c963f66afa6 HTTP/1.1
Authorization: Bearer <access_token>
X-Request-Id: 9b833995-54fd-4a05-8e74-455c1473875a

{
  "publicKeyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "active": true,
  "algorithm": "ED25519",
  "publicKey": "MCowBQYDK2VwAyEA...",
  "createdAt": "2026-06-23T14:05:09Z"
}

See Verifying Webhook Signatures for the verification process.