# Webhook Registration and Management

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

See [Events](/account-api/webhooks/events) for the complete event catalogue 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, confirm the applicable network
requirements with Axiym.

## 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.

```json
{
  "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`. The delivery has type `subscription.test` and data
`{ "test": "OK" }`.

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