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

# Create a webhook endpoint

> Creates a labeled webhook endpoint. Each enabled endpoint receives the same webhook events and signs requests with its own secret. The secret is returned once in this response and cannot be read again.



## OpenAPI

````yaml /openapi.json post /config/webhooks
openapi: 3.1.0
info:
  title: Vocobase Partner API
  version: '2.0'
  description: >-
    API for managing voice AI agents, documents, and calls on the Vocobase
    platform.
servers:
  - url: https://api.vocobase.com/api/v2
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Config
    description: >-
      Read and update partner configuration, webhook settings, and telephony
      credentials.
  - name: Agents
    description: Create, read, update, and delete voice AI agents.
  - name: Voices
    description: >-
      List voice tiers, available voices, and stream preview audio for agent
      configuration.
  - name: Documents
    description: Upload, manage, and delete knowledge base documents.
  - name: Agent Documents
    description: Link and unlink documents to agents for knowledge base integration.
  - name: Calls
    description: Initiate outbound calls and view call history.
  - name: Phone Numbers
    description: >-
      Import DIDs, assign agents for inbound routing, and re-sync carrier
      Application bindings.
  - name: Inbound Routing Policies
    description: >-
      Define pre-answer routing decisions for inbound calls before AI sessions
      are created.
  - name: Telephony Connections
    description: Create, list, rename, and disconnect named V2 telephony connections.
  - name: VoiceLink Management
    description: Manage VoiceLink reseller clients, DID mapping, and readiness sync.
  - name: Projects
    description: Organize agents into projects. Every agent belongs to exactly one project.
  - name: Dictionaries
    description: Speech-recognition dictionary CRUD and agent attachment.
  - name: Sessions
    description: Browser-initiated WebRTC voice sessions for in-app voice agents.
paths:
  /config/webhooks:
    post:
      tags:
        - Config
      summary: Create a webhook endpoint
      description: >-
        Creates a labeled webhook endpoint. Each enabled endpoint receives the
        same webhook events and signs requests with its own secret. The secret
        is returned once in this response and cannot be read again.
      operationId: createWebhookEndpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - label
                - url
              properties:
                label:
                  type: string
                  pattern: ^[a-z0-9][a-z0-9-]{0,30}$
                  description: >-
                    Partner-chosen endpoint label. Lowercase letters, numbers,
                    and hyphens only; 1-31 characters.
                  example: prod
                url:
                  type: string
                  format: uri
                  description: HTTPS URL that receives webhook events.
                  example: https://example.com/webhooks/vocobase
                enabled:
                  type: boolean
                  default: true
                  description: Whether the endpoint should receive new webhook events.
      responses:
        '201':
          description: Webhook endpoint created. Save the secret immediately.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    allOf:
                      - $ref: '#/components/schemas/PartnerWebhookEndpoint'
                      - type: object
                        properties:
                          secret:
                            type: string
                            description: >-
                              HMAC signing secret. Starts with `whsec_`.
                              Returned only once.
                          message:
                            type: string
              example:
                success: true
                data:
                  id: 12345678-abcd-1234-abcd-123456789012
                  label: prod
                  url: https://example.com/webhooks/vocobase
                  enabled: true
                  last_delivery_at: null
                  last_delivery_status: null
                  created_at: '2026-05-25T10:00:00.000Z'
                  updated_at: '2026-05-25T10:00:00.000Z'
                  secret: whsec_abc123...
                  message: Save this secret — it will not be shown again.
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Label already exists or endpoint limit reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    PartnerWebhookEndpoint:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Webhook endpoint ID.
        label:
          type: string
          description: Partner-chosen endpoint label.
        url:
          type: string
          format: uri
          description: HTTPS endpoint URL.
        enabled:
          type: boolean
          description: Whether this endpoint receives new webhook events.
        last_delivery_at:
          type:
            - string
            - 'null'
          format: date-time
        last_delivery_status:
          type:
            - integer
            - 'null'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
          required:
            - code
            - message
      required:
        - success
        - error
  responses:
    ValidationError:
      description: Validation error in request body or parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: VALIDATION_ERROR
              message: agent_name is required and must be max 50 characters
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: UNAUTHORIZED
              message: Invalid or missing API key
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: INTERNAL_ERROR
              message: An unexpected error occurred
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key in format: `rg_live_xxxx`. Pass as a Bearer token in the
        Authorization header.

````