Webhook Registration and 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 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.

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

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.

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

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

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.