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

# Create or rotate a webhook subscription

> Creates the (business, environment) webhook endpoint, or rotates the signing secret if one already exists. The plaintext secret is returned exactly once.



## OpenAPI

````yaml POST /v1/webhook-subscriptions
openapi: 3.0.0
info:
  title: Cleff API
  description: >-
    Payout orchestration platform. All endpoints under /v1/ require an API key
    in the Authorization header (Bearer ck_<env>_<id>_<secret>).
  version: 0.0.1
  contact: {}
servers:
  - url: https://api.usecleff.com
security: []
tags: []
paths:
  /v1/webhook-subscriptions:
    post:
      tags:
        - Webhook subscriptions
      summary: Create or rotate the webhook subscription for this environment
      description: >-
        Creates the (business, environment) webhook endpoint, or rotates the
        signing secret if one already exists. The plaintext secret is returned
        exactly once.
      operationId: WebhookSubscriptionsController_create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookSubscriptionDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateWebhookSubscriptionResponseDto'
        '401':
          description: Missing or invalid credentials
      security:
        - api_key: []
components:
  schemas:
    CreateWebhookSubscriptionDto:
      type: object
      properties:
        url:
          type: string
          example: https://api.example.com/cleff/webhooks
        enabled_events:
          type: array
          description: >-
            Opt-in allowlist of event types to receive. Only values from this
            enum are accepted; a value outside it is rejected on this request.
          example:
            - payout.disbursement_submitted
            - payout.acknowledged
            - payout.estimated_arrival_at
            - payout.disbursed
            - beneficiary.details_submitted
            - beneficiary.bank_account.registered
            - beneficiary.enrollment_rejected
          items:
            type: string
            enum:
              - payout.disbursement_submitted
              - payout.acknowledged
              - payout.estimated_arrival_at
              - payout.disbursed
              - beneficiary.details_submitted
              - beneficiary.bank_account.registered
              - beneficiary.enrollment_rejected
      required:
        - url
        - enabled_events
    CreateWebhookSubscriptionResponseDto:
      type: object
      properties:
        subscription:
          $ref: '#/components/schemas/WebhookSubscriptionDto'
        secret:
          type: string
          example: whsec_sandbox_F2x…
          description: >-
            Signing secret. Shown ONCE at creation (and on rotation). Cleff
            cannot recover it later.
      required:
        - subscription
        - secret
    WebhookSubscriptionDto:
      type: object
      properties:
        id:
          type: string
        environment:
          type: string
        url:
          type: string
        enabled_events:
          type: array
          items:
            type: string
        enabled:
          type: boolean
        created_at:
          type: string
      required:
        - id
        - environment
        - url
        - enabled_events
        - enabled
        - created_at
  securitySchemes:
    api_key:
      scheme: bearer
      bearerFormat: ck_<env>_<id>_<secret>
      type: http
      description: >-
        Cleff API key issued to a Business that self-registers via POST
        /v1/registration

````