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

# Create a webhook endpoint

> Register a destination URL for outbound webhooks. The `secret` (`whsec_…`) is returned **once** here.



## OpenAPI

````yaml /v3-beta/api-reference/openapi.yaml post /v3/webhook-endpoints
openapi: 3.1.0
info:
  title: Suby.fi Merchant API
  version: 3.0.0-beta
  description: >
    The **v3** public merchant API for Suby.fi. RESTful (plural,
    resource-oriented

    endpoints under the `/v3` prefix). Authenticate every request

    with your secret API key in the `X-Suby-Api-Key` header.


    - `sk_live_…` keys operate in **production** (real funds).

    - `sk_sandbox_…` keys operate in a fully simulated **sandbox** (test cards,
      Base Sepolia crypto, no real money). The environment is derived from the
      key prefix.

    All monetary amounts are **integer cents** (except `priceCents` on some

    read shapes, which is a string) — token amounts are strings in the smallest

    unit (sats / lamports / wei). Fees are basis points.
  contact:
    email: dev@suby.fi
    url: https://suby.fi
servers:
  - url: https://api.beta.suby.fi
    description: Production + sandbox (environment selected by API key prefix)
security:
  - ApiKeyAuth: []
tags:
  - name: Products
    description: Manage your product catalog (one-time and recurring).
  - name: Checkout
    description: >-
      Hosted checkout — signed session tokens (`cs_…`) plus branding and
      appearance settings.
  - name: Payments
    description: >-
      Create, capture, void, and retrieve one-time & off-session payments (card,
      APM, and crypto).
  - name: Subscriptions
    description: Start and cancel recurring subscriptions.
  - name: Customers
    description: First-class customer records with billing address.
  - name: Payment Methods
    description: >-
      Save a payment method to a customer and manage saved instruments for
      off-session charges.
  - name: Webhook Endpoints
    description: Register outbound webhook destinations and rotate signing secrets.
  - name: Analytics
    description: Org-wide revenue analytics.
  - name: Health
    description: Unauthenticated liveness probe.
paths:
  /v3/webhook-endpoints:
    post:
      tags:
        - Webhook Endpoints
      summary: Create a webhook endpoint
      description: >-
        Register a destination URL for outbound webhooks. The `secret`
        (`whsec_…`) is returned **once** here.
      operationId: createWebhookEndpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  format: uri
                  maxLength: 2048
                  pattern: ^https?://
                  description: Destination URL (http/https). Required.
                description:
                  type: string
                  maxLength: 500
                  description: Optional label.
                enabledEvents:
                  type: array
                  items:
                    type: string
                  default: []
                  description: >-
                    Event types to receive (e.g. `payment.succeeded`,
                    `subscription.updated`). Empty array = subscribe to ALL
                    events (default).
      responses:
        '201':
          description: Endpoint created (with plaintext secret)
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - properties:
                      data:
                        $ref: '#/components/schemas/WebhookEndpointWithSecret'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    SuccessEnvelope:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        data:
          description: Endpoint-specific payload.
    WebhookEndpointWithSecret:
      allOf:
        - $ref: '#/components/schemas/WebhookEndpoint'
        - type: object
          properties:
            secret:
              type: string
              example: whsec_…
              description: Plaintext signing secret — shown ONCE.
    WebhookEndpoint:
      type: object
      properties:
        id:
          type: string
          example: whep_abc123
        organizationId:
          type: string
        url:
          type: string
        description:
          type: string
          nullable: true
        enabledEvents:
          type: array
          items:
            type: string
          description: Empty = all events.
        isActive:
          type: boolean
        apiVersion:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Error:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Machine-readable error code.
          example: NOT_FOUND
        message:
          type: string
          example: Resource not found
        data:
          description: Optional error detail.
    ValidationErrorEnvelope:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            data:
              type: object
              properties:
                fieldErrors:
                  type: array
                  items:
                    type: object
                    properties:
                      field:
                        type: string
                      message:
                        type: string
  responses:
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: UNAUTHORIZED
            message: Invalid or missing API key
    ValidationError:
      description: Request failed schema validation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorEnvelope'
          example:
            success: false
            error: VALIDATION_ERROR
            message: Validation failed
            data:
              fieldErrors:
                - field: method
                  message: method is a required field
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Suby-Api-Key
      description: Secret API key. `sk_live_…` (production) or `sk_sandbox_…` (sandbox).

````