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

# List webhooks

> The webhooks of the user who created this API key, the same list as the dashboard's Webhooks page. Header values are never returned. Requires the webhooks:read scope.

| Requirement | Detail |
| - | - |
| **Scope** | `webhooks:read` |
| **Rate limit** | About 60 requests per minute per API key (shared by all endpoints; approximate) |
| **Cost** | Free |

> [!TIP]
>
> **Safety**
>
> * **Writes data:** No
> * **Safe to retry:** Yes
> * **Contacts an outside system:** None
> * **Dry run:** Not needed (read-only).

> [!NOTE]
>
> Rolling out: this endpoint is on staging first and not yet on `api.healos.ai`.

Webhooks belong to the user who created the API key and receive that user's note and document events, the same as on the dashboard's Webhooks page. A webhook of another user, in your organization or any other, is a `404`.

Header values are write-only: each webhook lists `header_names`, never the values.

Guide: [Webhooks](https://docs.healos.ai/webhooks.md). Errors: [Error catalog](https://docs.healos.ai/errors.md).


## OpenAPI

````yaml openapi/ext-api-v1.json GET /webhooks
openapi: 3.0.0
info:
  title: Healos External API
  version: 1.0.0
  description: >-
    External API for managing patients, documents, and appointments, listing
    providers and note templates, pulling clinical notes (with transcript and
    patient context), running insurance eligibility checks, browsing the EHR
    action catalog, reading AI Receptionist calls (summary, transcript,
    extracted details and recording), managing the AI Receptionist inbox tasks,
    and registering webhooks for note and document events.
servers:
  - url: https://api.healos.ai/ext-api/v1
    description: Production
  - url: http://localhost:8787/ext-api/v1
    description: Local development
security:
  - ApiKeyAuth: []
paths:
  /webhooks:
    get:
      tags:
        - Webhooks
      summary: List webhooks
      description: >-
        The webhooks of the user who created this API key, the same list as the
        dashboard's Webhooks page. Header values are never returned. Requires
        the webhooks:read scope.
      responses:
        '200':
          description: Your webhooks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookListResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient scope (needs webhooks:read)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
components:
  schemas:
    WebhookListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Webhook'
      required:
        - data
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
    RateLimitError:
      type: object
      properties:
        error:
          type: string
          example: Rate limit exceeded. Please retry after the window resets.
        code:
          type: string
          enum:
            - daily_cap_reached
          description: >-
            Set when the organization reached its daily cap for this paid
            operation (not on a per-minute limit).
        reset_at:
          type: string
          format: date-time
          description: 'With `code`: when the daily cap resets (next 00:00 UTC).'
          example: '2026-10-28T00:00:00.000Z'
      required:
        - error
    Webhook:
      type: object
      properties:
        id:
          type: string
          example: 3f2b8c1e-0000-4000-8000-000000000001
        name:
          type: string
        url:
          type: string
        event_type:
          type: string
          example: NOTE_CREATED
        format:
          type: string
          example: JSON
        description:
          type: string
          nullable: true
        header_names:
          type: array
          items:
            type: string
          description: >-
            The names of the configured headers. Their values are never
            returned.
          example:
            - Authorization
        active:
          type: boolean
        created_at:
          type: string
          example: '2026-11-03T14:00:00.000Z'
      required:
        - id
        - name
        - url
        - event_type
        - format
        - description
        - header_names
        - active
        - created_at
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key obtained from /api/v1/ext-api-keys

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.