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

# Create a subscription

> Registers a new webhook subscription so Verbex delivers selected event notifications to your endpoint as HTTP POST requests. Optionally scope it to specific agents or workspaces, filter the `events` it receives, and enable HMAC-signed delivery. Returns the created subscription - including a one-time signing `secret` when `enable_signed_webhooks` is `true`. The `secret` (prefixed `whsec_`) is returned only once at creation, so store it securely; if it's lost or leaked, rotate it via the rotate-secret endpoint.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/public/webhook/subscription
openapi: 3.1.0
info:
  title: Verbex Platform API
  description: API for managing AI agents, calls, phone numbers, and more.
  version: 1.0.0
servers: []
security: []
paths:
  /v1/public/webhook/subscription:
    post:
      tags:
        - Webhook Subscriptions
      summary: Create a subscription
      description: >-
        Registers a new webhook subscription so Verbex delivers selected event
        notifications to your endpoint as HTTP POST requests. Optionally scope
        it to specific agents or workspaces, filter the `events` it receives,
        and enable HMAC-signed delivery. Returns the created subscription -
        including a one-time signing `secret` when `enable_signed_webhooks` is
        `true`. The `secret` (prefixed `whsec_`) is returned only once at
        creation, so store it securely; if it's lost or leaked, rotate it via
        the rotate-secret endpoint.
      operationId: create_webhook_subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSubscriptionRequest'
            example:
              name: Payment Events Webhook
              description: Receives payment events with custom authentication
              url: https://api.example.com/webhooks/payments
              active: true
              enable_signed_webhooks: true
              events: []
              headers:
                X-Custom-Header: custom-value
                Authorization: Bearer your-api-token-here
      responses:
        '201':
          description: Created. Includes the one-time `secret` when signing is enabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscriptionResponse'
              example:
                id: 6a27a76692d9e3a8ffd7e62d
                organization_id: ddd6f1d8-b232-497e-bf1e-ea7317622d17
                scope: ORGANIZATION
                created_user_id: google-oauth2|101090478854418701727
                name: Payment Events Webhook
                url: https://api.example.com/webhooks/payments
                events: []
                active: true
                headers:
                  X-Custom-Header: custom-value
                  Authorization: Bearer your-api-token-here
                description: Receives payment events with custom authentication
                request_timeout_ms: 1000
                retry_policy:
                  retryStrategy: FIXED_DELAY
                  maxRetryAttempts: 3
                  maxRetryDelayMs: 10000
                signing_enabled: true
                secret: whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
                created_at: '2026-06-09T10:15:00.000Z'
                updated_at: '2026-06-09T10:15:00.000Z'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookErrorResponse'
          description: Bad Request - malformed JSON or invalid/missing fields.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookAuthErrorResponse'
          description: Unauthorized - missing or invalid Bearer token.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookErrorResponse'
          description: >-
            Conflict - duplicate name, or rotate-secret on an unsigned
            subscription.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookErrorResponse'
          description: Internal Server Error.
      security:
        - BearerAuth: []
components:
  schemas:
    WebhookSubscriptionRequest:
      type: object
      title: WebhookSubscriptionRequest
      required:
        - name
        - url
        - active
        - enable_signed_webhooks
      properties:
        name:
          type: string
          title: Name
          description: >-
            Display name for the subscription (non-blank; unique per
            organization).
          example: Payment Events Webhook
        url:
          type: string
          pattern: ^https?://.*
          title: Url
          description: >-
            Destination endpoint that receives event POSTs. Must match
            `^https?://.*`.
          example: https://api.example.com/webhooks/payments
        active:
          type: boolean
          title: Active
          description: Whether deliveries are attempted (`true`) or paused (`false`).
          example: true
        enable_signed_webhooks:
          type: boolean
          title: Enable Signed Webhooks
          description: >-
            HMAC signing toggle. Must be `true` or `false` (omitting it returns
            `400`). On create, `true` generates a `whsec_` signing secret
            returned once in the response; `false` creates an unsigned
            subscription. On update it also drives the signing lifecycle (enable
            or disable signing).
          example: true
        events:
          type: array
          items:
            type: string
          title: Events
          description: >-
            Event types to subscribe to, each in the case-sensitive
            `Service.Event` pattern (e.g. `CallHandler.CallStarted`). An empty
            array or `["*"]` subscribes to all events.
          example: []
        headers:
          type: object
          additionalProperties:
            type: string
          title: Headers
          description: >-
            Custom HTTP headers sent with each delivery (string->string map;
            e.g. auth tokens for your receiving endpoint).
          example:
            X-Custom-Header: custom-value
            Authorization: Bearer your-api-token-here
        description:
          type: string
          maxLength: 1500
          title: Description
          description: Free-text description (max 1500 chars).
          example: Receives payment events with custom authentication
        agent_ids:
          type: array
          items:
            type: string
          title: Agent Ids
          description: Scope the subscription to specific agents (`scope = AGENT`).
        workspace_ids:
          type: array
          items:
            type: string
          title: Workspace Ids
          description: Scope the subscription to specific workspaces (`scope = WORKSPACE`).
    WebhookSubscriptionResponse:
      type: object
      title: WebhookSubscriptionResponse
      properties:
        id:
          type: string
          title: Id
          description: Subscription ID. Required for GET / PUT / DELETE.
          example: 6a27a76692d9e3a8ffd7e62d
        organization_id:
          type: string
          title: Organization Id
          description: Owning organization (resolved from your API key).
          example: ddd6f1d8-b232-497e-bf1e-ea7317622d17
        scope:
          type: string
          enum:
            - ORGANIZATION
            - WORKSPACE
            - AGENT
          title: Scope
          description: Resolved delivery scope.
          example: ORGANIZATION
        created_user_id:
          type: string
          title: Created User Id
          description: User that created the subscription.
          example: google-oauth2|101090478854418701727
        name:
          type: string
          title: Name
          example: Payment Events Webhook
        url:
          type: string
          title: Url
          example: https://api.example.com/webhooks/payments
        events:
          type: array
          items:
            type: string
          title: Events
          example: []
        active:
          type: boolean
          title: Active
          example: true
        headers:
          type: object
          additionalProperties:
            type: string
          title: Headers
          description: >-
            Custom HTTP headers forwarded with each delivery; omitted when
            unset.
          example:
            X-Custom-Header: custom-value
            Authorization: Bearer your-api-token-here
        description:
          type: string
          title: Description
          description: Free-text description; omitted when unset.
          example: Receives payment events with custom authentication
        agent_ids:
          type: array
          items:
            type: string
          title: Agent Ids
          description: Agent scope; omitted when unset.
        workspace_ids:
          type: array
          items:
            type: string
          title: Workspace Ids
          description: Workspace scope; omitted when unset.
        request_timeout_ms:
          type: integer
          title: Request Timeout Ms
          description: Per-attempt delivery timeout in ms (default `1000`).
          example: 1000
        retry_policy:
          $ref: '#/components/schemas/WebhookRetryPolicy'
        signing_enabled:
          type: boolean
          title: Signing Enabled
          description: Whether the subscription has a signing secret. Always present.
          example: true
        secret:
          type: string
          title: Secret
          description: >-
            HMAC signing secret, prefixed `whsec_`. Present only at issuance
            when signing is enabled. Never returned by read endpoints.
          example: whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        created_at:
          type: string
          format: date-time
          title: Created At
          example: '2026-06-09T10:15:00.000Z'
        updated_at:
          type: string
          format: date-time
          title: Updated At
          example: '2026-06-09T10:15:00.000Z'
    WebhookErrorResponse:
      type: object
      title: WebhookErrorResponse
      description: Service-level error body (400, 404, 409, 500).
      properties:
        status:
          type: integer
          title: Status
          example: 400
        type:
          type: string
          title: Type
          example: VALIDATION_ERROR
        message:
          type: string
          title: Message
          example: Validation failed
        details:
          type: object
          title: Details
          description: >-
            Optional structured detail (e.g. `fields` -> per-field validation
            messages).
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        path:
          type: string
          title: Path
          example: /v1/public/webhook/subscription
        trace_id:
          type: string
          title: Trace Id
          example: 341b5325-a0be-4533-85dd-6f697476dfc3
    WebhookAuthErrorResponse:
      type: object
      title: WebhookAuthErrorResponse
      description: >-
        Authentication failures rejected at the API gateway (401) return this
        leaner body (note camelCase `traceId`).
      properties:
        error:
          type: string
          title: Error
          example: Authentication
        message:
          type: string
          title: Message
          example: Authentication failed
        traceId:
          type: string
          title: Trace Id
          example: e679120f-1d1c-41d2-947c-34e194d5a4a1
    WebhookRetryPolicy:
      type: object
      title: WebhookRetryPolicy
      description: Delivery retry configuration.
      properties:
        retryStrategy:
          type: string
          title: Retry Strategy
          example: FIXED_DELAY
        maxRetryAttempts:
          type: integer
          title: Max Retry Attempts
          example: 3
        maxRetryDelayMs:
          type: integer
          title: Max Retry Delay Ms
          example: 10000
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key passed as a Bearer token in the `Authorization` header:
        `Authorization: Bearer <YOUR_API_KEY>`.

````