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

# SIP hooks

> Returns the current list of SIP hooks from runtime state.
This endpoint requires authentication if `AUTH_REQUIRED=true`.

# Returns
* `200 OK` - List of SIP hooks
* `500 Internal Server Error` - If reading the cache fails

Lists all configured SIP hooks from the runtime state. Useful for debugging host-to-URL routing when forwarding LiveKit SIP webhooks.

## Response

Returns `{ hooks: [...] }` with each hook containing:

* `host` - Host pattern for matching SIP domains (case-insensitive)
* `url` - HTTPS URL to forward webhook events to
* `auth_id` - Tenant identifier for room ownership (used for `metadata.auth_id`)

<Note>
  The `auth_id` field associates inbound SIP calls with a specific tenant. When a call arrives, Sayna sets the room's `metadata.auth_id` to this value for access control.
</Note>

## Authorization

Requires authentication when `AUTH_REQUIRED=true`.


## OpenAPI

````yaml GET /sip/hooks
openapi: 3.1.0
info:
  title: Sayna API
  description: >-
    Real-time voice processing server with Speech-to-Text (STT) and
    Text-to-Speech (TTS) services
  contact:
    name: Sayna
    url: https://api.sayna.ai
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  version: 0.1.0
servers:
  - url: https://api.sayna.ai
    description: Production API
  - url: http://localhost:3001
    description: Local development
security: []
tags:
  - name: health
    description: Health check endpoints
  - name: voices
    description: TTS voice management
  - name: tts
    description: Text-to-speech synthesis
  - name: livekit
    description: LiveKit room and token management
  - name: recordings
    description: Recording download operations
  - name: sip
    description: SIP webhook configuration management
  - name: websocket
    description: WebSocket API for real-time communication
paths:
  /sip/hooks:
    get:
      tags:
        - sip
      summary: Lists all configured SIP hooks.
      description: |-
        Returns the current list of SIP hooks from runtime state.
        This endpoint requires authentication if `AUTH_REQUIRED=true`.

        # Returns
        * `200 OK` - List of SIP hooks
        * `500 Internal Server Error` - If reading the cache fails
      operationId: list_sip_hooks
      responses:
        '200':
          description: List of SIP hooks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SipHooksResponse'
        '500':
          description: Failed to read hooks cache
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SipHooksErrorResponse'
      security:
        - auth: []
components:
  schemas:
    SipHooksResponse:
      type: object
      description: Response body for SIP hooks operations.
      required:
        - hooks
      properties:
        hooks:
          type: array
          items:
            $ref: '#/components/schemas/SipHookEntry'
          description: List of all configured SIP hooks
    SipHooksErrorResponse:
      type: object
      description: Error response for SIP hooks operations.
      required:
        - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
          example: 'Duplicate host detected: example.com'
    SipHookEntry:
      type: object
      description: >-
        A single SIP hook entry.


        Note: The `auth_id` field is conditionally required based on
        `AUTH_REQUIRED`:

        - When `AUTH_REQUIRED=true`: `auth_id` must be provided and cannot be
        empty

        - When `AUTH_REQUIRED=false`: `auth_id` may be empty (unauthenticated
        mode)
      required:
        - host
        - url
        - auth_id
      properties:
        auth_id:
          type: string
          description: >-
            Tenant identifier for this hook (written to LiveKit room metadata).

            Required when AUTH_REQUIRED=true; may be empty when
            AUTH_REQUIRED=false.

            When empty, room metadata updates are skipped.
          example: tenant-123
        host:
          type: string
          description: Host pattern for matching SIP domains (case-insensitive)
          example: example.com
        url:
          type: string
          description: HTTPS URL to forward webhook events to
          example: https://webhook.example.com/events
  securitySchemes:
    auth:
      type: http
      scheme: bearer
      bearerFormat: Token
      description: >-
        Authentication token for protected endpoints. Can be provided as
        `Authorization: Bearer <token>` or `?api_key=<token>`. Required when
        AUTH_REQUIRED is enabled.

````