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

# Register a webhook endpoint

> Per-agent outbound webhook subscription. An agent with no subscription emits nothing. `headers` are replayed verbatim on every delivery and authenticate it; their values are never returned by any read. Signing is opt-in — `signing_secret` is returned **only here**, and only when `signing_enabled` is true. Scope `api_keys:write`.



## OpenAPI

````yaml /api-reference/openapi.json post /webhooks/subscriptions
openapi: 3.1.0
info:
  title: Lehar API
  version: v0
  description: >-
    Customer-facing REST API for the Lehar voice-AI platform. Platform-admin
    endpoints are intentionally excluded from this reference. Regenerate with
    `npm run sync:openapi`.
servers:
  - url: https://api.lehar.ai/ca/api/v0
security:
  - ApiKeyAuth: []
  - BearerAuth: []
paths:
  /webhooks/subscriptions:
    post:
      tags:
        - Webhook Subscriptions
      summary: Register a webhook endpoint
      description: >-
        Per-agent outbound webhook subscription. An agent with no subscription
        emits nothing. `headers` are replayed verbatim on every delivery and
        authenticate it; their values are never returned by any read. Signing is
        opt-in — `signing_secret` is returned **only here**, and only when
        `signing_enabled` is true. Scope `api_keys:write`.
      operationId: create_subscription_ca_api_v0_webhooks_subscriptions_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - agent_id
                - url
              properties:
                agent_id:
                  type: string
                  description: >-
                    The agent whose call events this endpoint receives. Cannot
                    be changed later; delete and recreate to move a
                    subscription.
                url:
                  type: string
                  description: >-
                    Absolute https:// URL. Max 2048 chars. Private and loopback
                    addresses are rejected.
                events:
                  type: array
                  description: Event types to receive. Empty or omitted means all.
                  items:
                    type: string
                    enum:
                      - call_started
                      - call_completed
                      - recording_completed
                headers:
                  type: object
                  description: >-
                    Static headers sent with every delivery — this is how your
                    endpoint authenticates us. Max 20 headers, 8 KB total.
                    Framing headers (Content-Type, Host, …) and the X-Webhook-*
                    family are reserved. Values are write-only.
                  additionalProperties:
                    type: string
                signing_enabled:
                  type: boolean
                  default: false
                  description: >-
                    Also send X-Webhook-Signature / X-Webhook-Timestamp. Off by
                    default: the headers above are the primary authentication.
                payload_format:
                  type: string
                  enum:
                    - native
                    - ringg
                  default: native
                  description: >-
                    Wire shape of the body. `ringg` reshapes it for a receiver
                    written against Ringg's webhooks.
                description:
                  type: string
            example:
              agent_id: agent_sales_hi
              url: https://hooks.example.com/lehar
              events:
                - call_completed
              headers:
                Authorization: Bearer your-receiver-token
              description: CRM sync
      responses:
        '201':
          description: >-
            Created. The only response carrying `signing_secret`, and only when
            signing was enabled.
          content:
            application/json:
              example:
                id: whsub_01EXAMPLE
                agent_id: agent_sales_hi
                url: https://hooks.example.com/lehar
                description: CRM sync
                events:
                  - call_completed
                status: active
                payload_format: native
                signing_enabled: false
                header_names:
                  - Authorization
                last_delivery_at: null
                last_error: null
                created_at: '2026-08-11T09:00:00Z'
                updated_at: '2026-08-11T09:00:00Z'
        '404':
          description: The agent does not exist, or does not belong to this workspace.
        '409':
          description: This agent already has an active subscription for the same URL.
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
    BearerAuth:
      type: http
      scheme: bearer

````