> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rails.wayex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a webhook subscription

> Registers an HTTPS endpoint to receive signed Wayex events for this tenant account.

## What this endpoint does

Registers an HTTPS endpoint to receive signed Wayex events for this tenant account.

## When to use it

Create one when your integration needs asynchronous transfer, Treasury, verification, or route updates.

## Before you call

Use a secret API key with webhook write access. The destination must be an HTTPS endpoint that can preserve the raw request body and store the signing secret securely.

## Money and balance effect

This changes a resource or configuration but does not directly reserve, debit, credit, or settle wallet money.

## States and completion

Creation confirms the subscription exists; it does not prove your endpoint acknowledged a delivery. Inspect delivery records and verify every signature.

## Safe retries

Send a unique `Idempotency-Key` for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out.

Read [Webhooks](/console/developers) for the complete workflow.


## OpenAPI

````yaml /api-reference/openapi.json post /v1/webhooks
openapi: 3.0.0
info:
  title: Wayex API
  description: >-
    Wayex APIs for direct customer payment routes and isolated, prefunded
    Treasury accounts. Each API key is bound to one tenant account and its own
    wallet, settings, webhooks, and reporting.
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.sandbox.wayex.com
    description: Sandbox integration environment
security:
  - Bearer: []
  - ApiKey: []
tags:
  - name: Treasury
    description: >-
      Prefunded AUD and stablecoin wallets for one isolated tenant account.
      Fund, pay, convert, withdraw, track, and reconcile without selecting
      another account.
  - name: Customers
    description: >-
      Onboard end customers, run verification, and manage each customer's
      entitlements.
  - name: Payment routes
    description: >-
      Standing deposit instructions per customer. When a customer funds a route,
      Wayex auto-converts at the live rate and pays out/sends — no quote, no
      lock.
  - name: Transfers
    description: >-
      Read the conversion records produced when customers fund payment routes —
      the live activity feed and per-conversion lifecycle timeline.
  - name: Rates
    description: >-
      The live indicative AUD↔stablecoin rate right now — the all-in rate Wayex
      quotes. Indicative only; the binding price is struck when a route's funds
      land.
  - name: Revenue
    description: Your developer-fee revenue over time.
  - name: Invoices
    description: >-
      Your monthly invoices — Wayex platform fees due, net of your accrued
      developer-fee credit.
  - name: Webhooks
    description: Subscribe to HMAC-signed event webhooks and inspect deliveries.
  - name: API keys
    description: Create, list, and rotate API keys for programmatic access.
  - name: Fees
    description: >-
      Configure your developer fee — the markup withheld from each conversion
      and credited against your monthly invoice.
  - name: Invitations
    description: Accept a team invitation and activate your account.
paths:
  /v1/webhooks:
    post:
      tags:
        - Webhooks
      summary: Create a webhook subscription
      description: >-
        Registers an HTTPS endpoint to receive signed Wayex events for this
        tenant account. Create one when your integration needs asynchronous
        transfer, Treasury, verification, or route updates.
      operationId: WebhookController2_subscribe_v1
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: >-
            A unique key for this logical action. Reuse the same key and
            identical payload when retrying after an unknown response.
          schema:
            type: string
            minLength: 8
            maxLength: 255
          example: 13bda8d7-87bd-4fa4-b7d5-e740725f9bd2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscribeWebhookDto'
      responses:
        '201':
          description: The created subscription (the signing secret is never echoed).
          content:
            application/json:
              schema:
                description: A webhook subscription (the signing secret is never echoed).
                type: object
                properties:
                  id:
                    description: The subscription id.
                    type: string
                  url:
                    description: The endpoint deliveries are sent to.
                    type: string
                    format: uri
                  eventTypes:
                    description: The event types subscribed to.
                    type: array
                    items:
                      type: string
                      enum:
                        - counterparty.created
                        - counterparty.invited
                        - counterparty.activated
                        - customer.created
                        - kyc.updated
                        - payment_route.created
                        - payment_route.activity.created
                        - rate.updated
                        - quote.created
                        - transfer.created
                        - transfer.updated
                        - transfer.completed
                        - treasury.wallet.updated
                        - treasury.payin.updated
                        - treasury.deposit.updated
                        - treasury.payout.updated
                        - treasury.withdrawal.updated
                        - treasury.conversion.updated
                        - approval.created
                        - approval.resolved
                  status:
                    description: Whether the subscription receives events.
                    type: string
                    enum:
                      - active
                      - disabled
                  createdAt:
                    description: When the subscription was created (ISO 8601).
                    type: string
                required:
                  - id
                  - url
                  - eventTypes
                  - status
                  - createdAt
        '400':
          description: >-
            Validation failed — invalid event types, or a url that is not https
            / resolves to a private, loopback or link-local address / cannot be
            resolved at all.
      security:
        - Bearer: []
        - ApiKey: []
components:
  schemas:
    SubscribeWebhookDto:
      type: object
      properties:
        url:
          description: >-
            The HTTPS endpoint Wayex POSTs signed event deliveries to. Must be
            https and must resolve to a public address — private, loopback,
            link-local and metadata destinations are refused.
          type: string
          format: uri
        eventTypes:
          description: The event types this subscription receives.
          type: array
          minItems: 1
          items:
            type: string
            enum:
              - counterparty.created
              - counterparty.invited
              - counterparty.activated
              - customer.created
              - kyc.updated
              - payment_route.created
              - payment_route.activity.created
              - rate.updated
              - quote.created
              - transfer.created
              - transfer.updated
              - transfer.completed
              - treasury.wallet.updated
              - treasury.payin.updated
              - treasury.deposit.updated
              - treasury.payout.updated
              - treasury.withdrawal.updated
              - treasury.conversion.updated
              - approval.created
              - approval.resolved
        secret:
          description: >-
            The HMAC signing secret; stored encrypted and never returned in any
            response.
          type: string
          minLength: 8
      required:
        - url
        - eventTypes
        - secret
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: Wayex API key
      description: 'Send the same Wayex API key as `Authorization: Bearer <key>`.'
    ApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: A Wayex API key. Use a secret key for write operations.

````