# Webhook Registration and Management

Product: Client Trade API
Guides follow API reference 0.3.0 and event reference 0.2.0.
Canonical page: https://docs.axiym.io/trade-api/webhooks/registration-management

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

The Client Trade API event catalogue covers deposits, withdrawals, conversions,
address book entries, and posted Axiym account balance movements.
Address book entry events retain the `destination.*` names used by
the contract. See [Events](/trade-api/webhooks/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.

The published contract does not define a source-IP allowlist. Confirm any
network restrictions with Axiym for your environment.

## Create a subscription

Use `POST /webhooks/subscriptions` to register an endpoint.

```http
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.

```json
{
  "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 required on subscription creation. Generate a fresh key
for each new subscription and reuse the original key when retrying the same
create request.

## List subscriptions

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

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

The response is paginated.

```json
{
  "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.

An `Idempotency-Key` is required. Use a fresh key for each new test and retain
that key when retrying the same test request.

```http
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.

```json
{
  "status": "OK"
}
```

The delivery is a `subscription.test` event with `data` equal to
`{ "test": "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.

```http
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.

```json
{
  "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.

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

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

See [Verifying Webhook Signatures](/trade-api/webhooks/verifying-signatures) for the
verification process.