# Registration and management

Create, list, test, and disable webhook subscriptions.

Product: Payment API
Guides follow API reference 0.1.0 and event reference 0.1.0.
Canonical page: https://docs.axiym.io/payment-api/webhooks/registration-and-management

A subscription points to one HTTPS endpoint. Each active endpoint receives the
Payment API events available to your partnership.

## Endpoint requirements

Your webhook endpoint must:

* use HTTPS and be publicly reachable by Axiym;
* accept JSON `POST` requests;
* verify signatures before processing;
* de-duplicate by event `id`; and
* return `2xx` only after the event is safely persisted or queued.

## Create a subscription

```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"
}
```

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

Store `subscriptionId` for testing and disabling the endpoint.

## List subscriptions

`GET /webhooks/subscriptions` returns active subscriptions using cursor-based
pagination.

## Test a subscription

Send `POST /webhooks/subscriptions/{subscriptionId}/tests` with an
`Idempotency-Key`. A `201 Created` response means the test request was
accepted, not that your webhook endpoint processed the delivery successfully.

The delivery is a `subscription.test` event with `data` equal to
`{ "test": "OK" }`.

Handle a test event exactly like another delivery: verify, de-duplicate,
persist, and acknowledge.

## Disable a subscription

`DELETE /webhooks/subscriptions/{subscriptionId}` stops new deliveries to that
endpoint. Disabled subscriptions are no longer returned by the list endpoint.

## Retrieve a public key

Use `X-Key-Id` from an incoming delivery with
`GET /webhooks/public-keys/{publicKeyId}`. Cache the key by identifier and fetch
again when an unfamiliar ID appears.