> ## Documentation Index
> Fetch the complete documentation index at: https://developers.stablepay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Register Webhook

> Register a URL to receive outbound event notifications.
Pass an empty `events` array to subscribe to all event types.


<Note>
  The `secret` field is returned **only once** at registration time. Store it securely — it cannot be retrieved again. Use it to verify incoming `Stablepay-Signature` headers on your endpoint.
</Note>


## OpenAPI

````yaml POST /v1/webhooks/register
openapi: 3.0.3
info:
  title: Stablepay Money API
  description: >
    The Stablepay Money API enables wallet issuers to execute stablecoin-to-fiat

    payouts across Sub-Saharan Africa via M-Pesa, mobile money, and bank
    transfers.
  version: 0.5.0
  contact:
    name: Stablepay Engineering
    email: hello@stablepay.io
servers:
  - url: https://api.stablepay.ai
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Health
    description: Service liveness check.
  - name: FX
    description: Live FX rate conversion between USDC and local fiat currencies.
  - name: Payments
    description: Submit and track stablecoin-to-fiat payout requests.
  - name: Balances
    description: >-
      Live on-chain USDC and native token balances for the tenant's custody
      wallets.
  - name: Analytics
    description: >-
      Pre-aggregated payment analytics — volume, success rates, corridor
      breakdowns, and daily time series.
  - name: Customers
    description: |
      KYC API for DeFi wallets. Onboard and verify your end-users, then link
      their wallet addresses so verified identity travels with their on-chain
      activity.
  - name: Webhooks
    description: Register endpoints and manage outbound event delivery.
  - name: Admin
    description: >-
      Ops-only endpoints for tenant management and payment operations. Requires
      an admin-scoped API key.
paths:
  /v1/webhooks/register:
    post:
      tags:
        - Webhooks
      summary: Register a webhook endpoint
      description: |
        Register a URL to receive outbound event notifications.
        Pass an empty `events` array to subscribe to all event types.
      operationId: registerWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                  description: Your HTTPS endpoint that will receive POST requests.
                  example: https://app.walletIssuer.io/webhooks/stablepay
                events:
                  type: array
                  items:
                    type: string
                  description: Event types to subscribe to. Empty array = all events.
                  example:
                    - payment.succeeded
                    - payment.failed
                    - payment.processing
                    - customer.kyc.updated
              required:
                - url
            example:
              url: https://app.walletIssuer.io/webhooks/stablepay
              events:
                - payment.succeeded
                - payment.failed
                - payment.processing
                - customer.kyc.updated
      responses:
        '201':
          description: >-
            Webhook registered. Save the `secret`. It is not retrievable after
            this response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhookId:
                    type: string
                    format: uuid
                    description: Registration ID.
                  url:
                    type: string
                    format: uri
                  events:
                    type: array
                    items:
                      type: string
                  secret:
                    type: string
                    description: >
                      HMAC signing secret that is returned **once only**. Store
                      in your secrets manager.

                      Used to verify `Stablepay-Signature` on inbound events.
                    example: a3f7c2e1d4b8a0...
                required:
                  - webhookId
                  - url
                  - events
                  - secret
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        Stablepay API key. Include as `Authorization: Bearer <key>`.

````