openapi: 3.1.0
info:
  title: Axiym Client Account API Events
  version: 0.2.0
  description: |-
    This reference describes the webhook events Axiym sends to your registered HTTPS endpoint for Client Account API activity. Events notify your application about client availability, account movements, and changes to deposits, conversions, withdrawals, and registered external accounts.

    Subscriptions belong to your partnership. Events about client resources include `clientId` to identify the relevant client. Each event identifies the affected resource and describes the change. Retrieve the corresponding Client Account API resource when you need its current state or additional details.

    Verify every event signature. Deliveries may repeat, so use the event `id` to avoid processing the same event more than once. Acknowledge successfully received events with an HTTP `200` response.

    To start receiving events, see [Webhook Registration & Management](/client-account-api/webhooks/registration-management) and [Verifying Webhook Signatures](/client-account-api/webhooks/verifying-signatures).
tags:
  - name: Withdrawal
    description: Notifications about the lifecycle of an outbound withdrawal.
  - name: Account
    description: Notifications about posted Axiym account movements and changes to Axiym account availability.
  - name: Client
    description: "Notifications about client records, onboarding, and availability for Client Account API operations."
  - name: Address book entry
    description: "Notifications about the review and availability of external bank accounts and wallets registered in the selected client's address book."
  - name: Deposit
    description: Notifications about the lifecycle of an incoming deposit.
  - name: Conversion
    description: Notifications about the lifecycle of a currency conversion.
  - name: Webhook subscription
    description: Test notification sent when you request a delivery to a registered endpoint.
paths:
  /webhooks/withdrawal.created:
    post:
      tags:
        - Withdrawal
      summary: Withdrawal created
      description: Sent once a withdrawal has been confirmed and accepted for execution.
      operationId: onWithdrawalCreated
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: withdrawal.created
                data:
                  $ref: "#/components/schemas/WithdrawalEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/withdrawal.held:
    post:
      tags:
        - Withdrawal
      summary: Withdrawal held
      description: Sent when processing of a withdrawal has been placed temporarily on hold.
      operationId: onWithdrawalHeld
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: withdrawal.held
                data:
                  $ref: "#/components/schemas/WithdrawalEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/withdrawal.completed:
    post:
      tags:
        - Withdrawal
      summary: Withdrawal completed
      description: Sent when a withdrawal has completed successfully.
      operationId: onWithdrawalCompleted
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: withdrawal.completed
                data:
                  $ref: "#/components/schemas/WithdrawalEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/withdrawal.canceled:
    post:
      tags:
        - Withdrawal
      summary: Withdrawal canceled
      description: Sent when a withdrawal has been canceled and will not complete.
      operationId: onWithdrawalCanceled
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: withdrawal.canceled
                data:
                  $ref: "#/components/schemas/WithdrawalEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/withdrawal.rejected:
    post:
      tags:
        - Withdrawal
      summary: Withdrawal rejected
      description: Sent when a withdrawal has been rejected and will not complete.
      operationId: onWithdrawalRejected
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: withdrawal.rejected
                data:
                  $ref: "#/components/schemas/WithdrawalEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/account.credited:
    post:
      tags:
        - Account
      summary: Account credited
      description: Sent when a credit has been posted to an account.
      operationId: onAccountCredited
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: account.credited
                data:
                  $ref: "#/components/schemas/AccountMovementEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/account.debited:
    post:
      tags:
        - Account
      summary: Account debited
      description: Sent when a debit has been posted to an account.
      operationId: onAccountDebited
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: account.debited
                data:
                  $ref: "#/components/schemas/AccountMovementEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/account.activated:
    post:
      tags:
        - Account
      summary: Account activated
      description: Sent when an account becomes active and available for supported operations.
      operationId: onAccountActivated
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: account.activated
                data:
                  $ref: "#/components/schemas/AccountStatusEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/account.suspended:
    post:
      tags:
        - Account
      summary: Account suspended
      description: Sent when an account is suspended and temporarily unavailable for supported operations.
      operationId: onAccountSuspended
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: account.suspended
                data:
                  $ref: "#/components/schemas/AccountStatusEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/account.closed:
    post:
      tags:
        - Account
      summary: Account closed
      description: Sent when an account is permanently closed.
      operationId: onAccountClosed
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: account.closed
                data:
                  $ref: "#/components/schemas/AccountStatusEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/destination.created:
    post:
      tags:
        - Address book entry
      summary: Address book entry created
      description: "Sent when an external bank account or wallet is registered in the selected client's address book with status `PENDING_REVIEW`, awaiting due diligence and compliance checks."
      operationId: onDestinationCreated
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: destination.created
                data:
                  $ref: "#/components/schemas/DestinationEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/destination.activated:
    post:
      tags:
        - Address book entry
      summary: Address book entry activated
      description: "Sent when due diligence and compliance checks are complete and an external account becomes `ACTIVE`, whitelisted for deposits and withdrawals."
      operationId: onDestinationActivated
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: destination.activated
                data:
                  $ref: "#/components/schemas/DestinationEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/destination.suspended:
    post:
      tags:
        - Address book entry
      summary: Address book entry suspended
      description: "Sent when a registered external account is suspended and cannot be used for deposits or withdrawals."
      operationId: onDestinationSuspended
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: destination.suspended
                data:
                  $ref: "#/components/schemas/DestinationEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/destination.closed:
    post:
      tags:
        - Address book entry
      summary: Address book entry closed
      description: "Sent when a registered external account is permanently closed and can no longer be used for deposits or withdrawals."
      operationId: onDestinationClosed
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: destination.closed
                data:
                  $ref: "#/components/schemas/DestinationEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/deposit.created:
    post:
      tags:
        - Deposit
      summary: Deposit created
      description: Sent when an incoming payment has been detected and recorded as a deposit.
      operationId: onDepositCreated
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: deposit.created
                data:
                  $ref: "#/components/schemas/DepositEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/deposit.held:
    post:
      tags:
        - Deposit
      summary: Deposit held
      description: Sent when processing of a deposit has been placed temporarily on hold.
      operationId: onDepositHeld
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: deposit.held
                data:
                  $ref: "#/components/schemas/DepositEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/deposit.completed:
    post:
      tags:
        - Deposit
      summary: Deposit completed
      description: Sent when a deposit has completed and the receiving account has been credited.
      operationId: onDepositCompleted
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: deposit.completed
                data:
                  $ref: "#/components/schemas/DepositEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/deposit.canceled:
    post:
      tags:
        - Deposit
      summary: Deposit canceled
      description: Sent when a deposit has been canceled and will not be credited to the receiving account.
      operationId: onDepositCanceled
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: deposit.canceled
                data:
                  $ref: "#/components/schemas/DepositEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/deposit.rejected:
    post:
      tags:
        - Deposit
      summary: Deposit rejected
      description: Sent when a deposit has been rejected and will not be credited to the receiving account.
      operationId: onDepositRejected
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: deposit.rejected
                data:
                  $ref: "#/components/schemas/DepositEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/conversion.created:
    post:
      tags:
        - Conversion
      summary: Conversion created
      description: Sent once a conversion has been confirmed and execution has begun.
      operationId: onConversionCreated
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: conversion.created
                data:
                  $ref: "#/components/schemas/ConversionEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/conversion.completed:
    post:
      tags:
        - Conversion
      summary: Conversion completed
      description: Sent when a conversion has completed and the sell-side and buy-side Axiym account movements have been posted.
      operationId: onConversionCompleted
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: conversion.completed
                data:
                  $ref: "#/components/schemas/ConversionEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/conversion.canceled:
    post:
      tags:
        - Conversion
      summary: Conversion canceled
      description: Sent when a conversion has been canceled, expired, or failed and will not complete.
      operationId: onConversionCanceled
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - 2026-07-14T20:08:00Z
                type:
                  type: string
                  const: conversion.canceled
                data:
                  $ref: "#/components/schemas/ConversionEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/client.onboarding-finished:
    post:
      tags:
        - Client
      summary: Client onboarding finished
      description: "Deprecated legacy activation event. It is emitted alongside `client.activated` for the same activation moment until legacy integrators migrate."
      deprecated: true
      operationId: onClientOnboardingFinished
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                type:
                  type: string
                  const: client.onboarding-finished
                data:
                  $ref: "#/components/schemas/ClientOnboardingEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/client.created:
    post:
      tags:
        - Client
      summary: Client created
      description: Sent when Axiym creates a client record for your partnership.
      operationId: onClientCreated
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                timestamp:
                  type: string
                  format: date-time
                type:
                  type: string
                  const: client.created
                data:
                  $ref: "#/components/schemas/ClientEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/client.updated:
    post:
      tags:
        - Client
      summary: Client updated
      description: Sent when Axiym updates a client record. A disabled or archived update also emits `client.disabled`.
      operationId: onClientUpdated
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                timestamp:
                  type: string
                  format: date-time
                type:
                  type: string
                  const: client.updated
                data:
                  $ref: "#/components/schemas/ClientEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/client.activated:
    post:
      tags:
        - Client
      summary: Client activated
      description: Sent when an onboarded client becomes available for Client Account API operations, including when a previously disabled client is reactivated.
      operationId: onClientActivated
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                type:
                  type: string
                  const: client.activated
                data:
                  $ref: "#/components/schemas/ClientStatusEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/client.disabled:
    post:
      tags:
        - Client
      summary: Client disabled
      description: Sent when an onboarded client can no longer use Client Account API operations. Do not create new Client Account API resources for the client until it is activated again.
      operationId: onClientDisabled
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                type:
                  type: string
                  const: client.disabled
                data:
                  $ref: "#/components/schemas/ClientStatusEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/subscription.test:
    post:
      tags:
        - Webhook subscription
      summary: Webhook subscription test
      description: Sent only when you request a test delivery for a webhook subscription.
      operationId: onSubscriptionTest
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: "Unique event identifier. Repeated deliveries of the same event carry the same `id`; use it to avoid processing the event more than once."
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                type:
                  type: string
                  const: subscription.test
                data:
                  type: object
                  required:
                    - test
                  properties:
                    test:
                      type: string
                      const: OK
                      description: Test delivery marker.
      responses:
        "200":
          description: Acknowledged by your endpoint.
components:
  parameters:
    WebhookSignature:
      name: X-Signature
      in: header
      required: true
      schema:
        type: string
      description: "Base64-encoded Ed25519 signature of the raw HTTP request body bytes. Verify it before parsing or re-serializing the JSON."
    WebhookKeyId:
      name: X-Key-Id
      in: header
      required: true
      schema:
        type: string
        format: uuid
      description: "Identifier of the public key used to verify the delivery signature. Retrieve it with `GET /webhooks/public-keys/{publicKeyId}`."
    WebhookAlgorithm:
      name: X-Algorithm
      in: header
      required: true
      schema:
        type: string
        const: Ed25519
      description: Signature algorithm used for the delivery.
  schemas:
    ClientEventData:
      type: object
      description: Client record snapshot at the time of the event. Fetch `GET /clients/{clientId}` when current profile details are required.
      required:
        - clientId
        - legalEntityName
        - paymentRails
        - currency
        - status
      properties:
        clientId:
          type: string
          format: uuid
        code:
          type: string
          description: Human-readable Axiym client code, where available.
        legalEntityName:
          type: string
        paymentRails:
          type: string
        currency:
          type: string
        status:
          type: string
    ClientOnboardingEventData:
      type: object
      description: Compact outcome of a client onboarding review. Fetch `GET /onboardings/{clientId}` for the authoritative case, including any available rejection reason.
      required:
        - clientId
        - partnerClientId
        - status
      properties:
        clientId:
          type: string
          format: uuid
          description: Axiym identifier assigned to the represented client.
          examples:
            - 1d2f7f5e-8a3b-4c6d-9e0f-2a4b6c8d0e2f
        partnerClientId:
          type: string
          description: Your stable identifier for the client.
          examples:
            - acme-sg-001
        status:
          type: string
          description: Terminal onboarding decision.
          enum:
            - ACTIVE
            - REJECTED
          examples:
            - ACTIVE
    ClientStatusEventData:
      type: object
      description: Compact client availability change. Fetch `GET /clients/{clientId}` when current profile details are required.
      required:
        - clientId
        - status
      properties:
        clientId:
          type: string
          format: uuid
          description: Axiym identifier of the represented client.
          examples:
            - 1d2f7f5e-8a3b-4c6d-9e0f-2a4b6c8d0e2f
        status:
          type: string
          description: Client availability at the time the event was emitted.
          enum:
            - ACTIVE
            - DISABLED
          examples:
            - ACTIVE
    ConversionStatus:
      type: string
      description: |
        `PENDING` after creation (awaiting confirmation at the locked rate), `ACTIVE` once confirmed (executing), `COMPLETED` when the funds are exchanged, `CANCELED` if canceled, expired, or failed (see `reasonCode`).
      enum:
        - PENDING
        - ACTIVE
        - COMPLETED
        - CANCELED
      examples:
        - COMPLETED
    ConversionEventData:
      type: object
      description: "A compact notification for routing and correlation. Retrieve the conversion from `GET /clients/{clientId}/conversions/{conversionId}` when you need its amounts, rate, or current state."
      required:
        - conversionId
        - status
        - clientId
      properties:
        conversionId:
          type: string
          format: uuid
          description: Conversion identifier (UUID).
          examples:
            - a3f5d7c9-1e2b-4c6a-8d9f-0b1a2c3d4e5f
        status:
          $ref: "#/components/schemas/ConversionStatus"
          description: Conversion status at the time the event was emitted.
          examples:
            - COMPLETED
        externalReference:
          $ref: "#/components/schemas/ExternalReference"
          description: Your reference submitted on creation, where present.
          examples:
            - conv-2026-0714-01
        reasonCode:
          type: string
          description: "Present on `conversion.canceled` — the reason as reported by operations or the liquidity venue. Example: `RATE_EXPIRED`."
        clientId:
          type: string
          format: uuid
          description: Axiym identifier of the client that owns the resource.
          examples:
            - 1d2f7f5e-8a3b-4c6d-9e0f-2a4b6c8d0e2f
    DepositStatus:
      type: string
      description: |-
        `PENDING` awaits crediting. `HELD` is temporarily on hold. `COMPLETED` was credited to the account. `CANCELED` or `REJECTED` was not completed; see `reasonCode`.
      enum:
        - PENDING
        - HELD
        - COMPLETED
        - CANCELED
        - REJECTED
      examples:
        - COMPLETED
    DepositEventData:
      type: object
      description: "A compact notification for routing and correlation. Retrieve the deposit from `GET /clients/{clientId}/deposits/{depositId}` when you need its amount, transaction hash, or current state."
      required:
        - depositId
        - status
        - clientId
      properties:
        depositId:
          type: string
          format: uuid
          description: Deposit identifier (UUID).
          examples:
            - 4c8e2b6a-1d9f-4e3b-a7c5-2f0a8d6b4e1c
        status:
          $ref: "#/components/schemas/DepositStatus"
          description: Deposit status at the time the event was emitted.
          examples:
            - COMPLETED
        reasonCode:
          type: string
          description: "Present on `deposit.canceled` / `deposit.rejected` — the reason as reported by the bank, the network, or Axiym operations. Example: `SENDER_SCREENING_FAILED`."
        clientId:
          type: string
          format: uuid
          description: Axiym identifier of the client that owns the resource.
          examples:
            - 1d2f7f5e-8a3b-4c6d-9e0f-2a4b6c8d0e2f
    DestinationStatus:
      type: string
      description: "`PENDING_REVIEW` awaits due diligence and compliance checks. `ACTIVE` is whitelisted for deposits and withdrawals. `SUSPENDED` is temporarily unavailable. `CLOSED` is permanently retired."
      enum:
        - PENDING_REVIEW
        - ACTIVE
        - SUSPENDED
        - CLOSED
      examples:
        - ACTIVE
    DestinationEventData:
      type: object
      description: "Notification about the review or availability of an external account registered in the selected client's address book. `destinationId` identifies its address book entry."
      required:
        - destinationId
        - status
        - clientId
      properties:
        destinationId:
          type: string
          format: uuid
          description: "Identifier of the external account in the selected client's address book (UUID)."
          examples:
            - e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c
        status:
          $ref: "#/components/schemas/DestinationStatus"
          description: "External account status at the time the event was emitted."
          examples:
            - ACTIVE
        clientId:
          type: string
          format: uuid
          description: "Axiym identifier of the client whose address book contains the external account."
          examples:
            - 1d2f7f5e-8a3b-4c6d-9e0f-2a4b6c8d0e2f
    Currency:
      type: string
      description: Currency code — ISO 4217 (e.g. USD, EUR) or a supported digital currency (USDT, USDC).
      examples:
        - USD
    Decimal:
      type: string
      description: Decimal number serialized as a string to preserve precision.
      examples:
        - "1000.00"
    AccountStatus:
      description: "`ACTIVE` is available for supported operations. `SUSPENDED` is temporarily unavailable for supported operations. `CLOSED` is permanently closed."
      type: string
      enum:
        - ACTIVE
        - SUSPENDED
        - CLOSED
      examples:
        - SUSPENDED
    AccountMovementEventData:
      type: object
      description: "A posted account movement. The event includes the movement amount but not the current balance. Retrieve the account when you need its latest balance."
      required:
        - accountId
        - amount
        - currency
        - occurredAt
        - clientId
      properties:
        accountId:
          type: string
          format: uuid
          description: Account identifier (UUID).
          examples:
            - 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a
        amount:
          allOf:
            - $ref: "#/components/schemas/Decimal"
          description: Positive movement amount in the account currency; direction is in the event type.
          examples:
            - "500.00"
        currency:
          $ref: "#/components/schemas/Currency"
          description: Account currency.
          examples:
            - USDT
        relatedResourceType:
          type: string
          description: Type of the linked money movement; absent for movements with no linked API resource.
          enum:
            - DEPOSIT
            - WITHDRAWAL
            - CONVERSION
            - PAYOUT
            - TRANSFER
          examples:
            - WITHDRAWAL
        relatedResourceId:
          type: string
          format: uuid
          description: Identifier of the linked resource, where present.
          examples:
            - 9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e
        occurredAt:
          type: string
          format: date-time
          description: When the movement occurred. Formatted in ISO 8601.
          examples:
            - 2026-07-14T20:07:31Z
        clientId:
          type: string
          format: uuid
          description: Axiym identifier of the client that owns the resource.
          examples:
            - 1d2f7f5e-8a3b-4c6d-9e0f-2a4b6c8d0e2f
    AccountStatusEventData:
      type: object
      description: Account lifecycle notification.
      required:
        - accountId
        - status
        - clientId
      properties:
        accountId:
          type: string
          format: uuid
          description: Account identifier (UUID).
          examples:
            - 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a
        status:
          $ref: "#/components/schemas/AccountStatus"
          description: Account status at the time the event was emitted.
          examples:
            - SUSPENDED
        clientId:
          type: string
          format: uuid
          description: Axiym identifier of the client that owns the resource.
          examples:
            - 1d2f7f5e-8a3b-4c6d-9e0f-2a4b6c8d0e2f
    ExternalReference:
      type: string
      maxLength: 255
      description: "Your optional identifier for correlating the resource with your system. Axiym returns it on reads. It does not make retries safe; use `Idempotency-Key` for that."
      examples:
        - wd-2026-0714-01
    WithdrawalStatus:
      type: string
      description: "`PENDING` is queued for execution. `HELD` is temporarily on hold. `COMPLETED` means the withdrawal finished successfully. `CANCELED` and `REJECTED` did not complete (see `reasonCode`)."
      enum:
        - PENDING
        - HELD
        - COMPLETED
        - CANCELED
        - REJECTED
      examples:
        - PENDING
    WithdrawalEventData:
      type: object
      description: "A compact notification for routing and correlation. Retrieve the withdrawal from `GET /clients/{clientId}/withdrawals/{withdrawalId}` when you need its amount, fees, transaction hash, or current state."
      required:
        - withdrawalId
        - status
        - clientId
      properties:
        withdrawalId:
          type: string
          format: uuid
          description: Withdrawal identifier (UUID).
          examples:
            - 9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e
        status:
          $ref: "#/components/schemas/WithdrawalStatus"
          description: Withdrawal status at the time the event was emitted.
          examples:
            - COMPLETED
        externalReference:
          $ref: "#/components/schemas/ExternalReference"
          description: Your reference submitted on creation, where present.
          examples:
            - wd-2026-0714-01
        reasonCode:
          type: string
          description: "Present on `withdrawal.canceled` / `withdrawal.rejected` — the reason as reported by the bank, the network, or Axiym operations. Example: `INSUFFICIENT_BENEFICIARY_DETAILS`."
        clientId:
          type: string
          format: uuid
          description: Axiym identifier of the client that owns the resource.
          examples:
            - 1d2f7f5e-8a3b-4c6d-9e0f-2a4b6c8d0e2f