# Webhook Registration and Management

Product: Client Account API
Guides follow API reference 0.3.0 and event reference 0.2.0.
Canonical page: https://docs.sandbox.axiym.io/client-account-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 Account
API webhook events to each active subscription.

The Client Account API event catalogue covers client onboarding and availability,
deposits, withdrawals, conversions, registered external accounts, and Axiym
accounts. External-account events use the `destination.*` prefix and describe
their review and availability.
See [Events](/client-account-api/webhooks/events) for event names and payload shapes.

Subscriptions belong to your partnership. Manage them through `/webhooks/...`
using your partner access token; these endpoints have no `/clients/{clientId}`
prefix. A subscription receives events across your clients. Use `data.clientId`
to route client resource events.

## 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 after a timeout or ambiguous response.

## 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
it when retrying that 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. This does not
confirm successful delivery or processing by your endpoint.

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

The delivery is a `subscription.test` event with `data` equal to
`{ "test": "OK" }`. It has no `clientId`; handle it separately from client
resource events.

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](/client-account-api/webhooks/verifying-signatures) for the
verification process.