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

# Create a webhook endpoint



## OpenAPI

````yaml /openapi.json post /v1/webhooks
openapi: 3.0.0
info:
  contact: {}
  description: >-
    Comprehensive payment platform API supporting fiat and crypto payments,
    currency conversion, and compliance management
  title: Zuba Payment Platform API
  version: '1.0'
servers: []
security: []
tags:
  - description: Manage M2M API keys and credentials
    name: API Keys
  - description: Internal ledger accounts and transactions
    name: Ledger
  - description: Handle incoming payments and deposits
    name: Pay-ins
  - description: Manage payouts, beneficiaries, and SEPA transfers
    name: Payouts
  - description: Manage outbound webhook endpoints and deliveries
    name: Webhooks
paths:
  /v1/webhooks:
    post:
      tags:
        - Webhooks
      summary: Create a webhook endpoint
      operationId: WebhookController_create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookEndpointDto'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointCreatedResponseDto'
          description: Webhook endpoint created. Signing secret is shown only once.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponseDto'
          description: Validation error
        '401':
          description: Unauthorized
      security:
        - bearer: []
components:
  schemas:
    CreateWebhookEndpointDto:
      properties:
        enabled:
          default: true
          description: Whether the endpoint is enabled
          type: boolean
        events:
          description: Event types to subscribe to
          example:
            - payout.paid
            - payout.failed
          items:
            enum:
              - payout.processing
              - payout.paid
              - payout.failed
              - payout.reverted
              - payout.cancelled
              - webhook.test
              - account.created
            type: string
          type: array
        url:
          description: HTTPS URL to receive webhook events
          example: https://example.com/webhooks
          type: string
      required:
        - url
        - events
      type: object
    WebhookEndpointCreatedResponseDto:
      properties:
        createdAt:
          description: Creation timestamp
          type: string
        enabled:
          description: Whether the endpoint is enabled
          type: boolean
        events:
          description: Subscribed event types
          items:
            enum:
              - payout.processing
              - payout.paid
              - payout.failed
              - payout.reverted
              - payout.cancelled
              - webhook.test
              - account.created
            type: string
          type: array
        id:
          description: Endpoint ID
          type: string
        signingSecret:
          description: >-
            Signing secret (plaintext, shown only once). Use this to verify
            webhook signatures.
          example: whsec_a1b2c3d4e5f6...
          type: string
        signingSecretHint:
          description: Last 4 characters of the signing secret
          example: ab1f
          type: string
        updatedAt:
          description: Last update timestamp
          type: string
        url:
          description: Webhook URL
          type: string
      required:
        - id
        - url
        - events
        - enabled
        - signingSecretHint
        - createdAt
        - updatedAt
        - signingSecret
      type: object
    ValidationErrorResponseDto:
      properties:
        details:
          description: Array of detailed validation errors
          example:
            - field: accounts.0.data.crAccount
              message: crAccount must be exactly 10 digits for Nigerian accounts
              value: '12345678901'
          items:
            $ref: '#/components/schemas/ValidationErrorDetailDto'
          type: array
        error:
          description: Error type identifier
          example: BAD_REQUEST
          type: string
        message:
          description: Error summary message
          example: Validation failed
          type: string
        path:
          description: Request path that generated the error
          example: /v1/beneficiaries
          type: string
        statusCode:
          description: HTTP status code
          example: 400
          type: number
        timestamp:
          description: ISO timestamp when the error occurred
          example: '2024-01-15T10:30:00.000Z'
          type: string
      required:
        - statusCode
        - message
        - error
        - timestamp
        - path
        - details
      type: object
    ValidationErrorDetailDto:
      properties:
        code:
          description: >-
            Stable machine-readable code for client-side branching. Present on
            provider structural-validation failures (e.g.
            MISSING_BENEFICIARY_NAME, INVALID_IBAN, BENEFICIARY_INCOMPLETE);
            absent on generic DTO validation errors.
          example: MISSING_BENEFICIARY_NAME
          type: string
        field:
          description: The field path that failed validation
          example: accounts.0.data.crAccount
          type: string
        message:
          description: Human-readable error message describing the validation failure
          example: crAccount must be exactly 10 digits for Nigerian accounts
          type: string
        value:
          description: The invalid value that was provided (may be omitted for security)
          example: '12345678901'
          type: object
      required:
        - field
        - message
      type: object
  securitySchemes:
    bearer:
      bearerFormat: JWT
      description: Enter Auth0 JWT token
      scheme: bearer
      type: http

````