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

# List webhook endpoints

> List webhook endpoints for this account. Optional `event` filter uses names (`fax_received`). Requires webhooks to be enabled in Integrations. (Permitted scopes: **fax:all:read**, **fax:webhook:read**)

<Note>
  Current webhook API. Requires webhooks enabled in [Integrations](https://app.fax.plus/profile/integrations). For the older one-event-per-hook API, see [List user webhooks (Legacy)](/api-reference/endpoints/webhooks/list-user-webhooks).
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://restapi.fax.plus/v3/webhooks?event=fax_received&limit=50' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer {access-token}'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.get(
      "https://restapi.fax.plus/v3/webhooks",
      params={"event": "fax_received", "limit": 50},
      headers={"Authorization": "Bearer {access-token}", "Accept": "application/json"},
  )
  print(resp.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "ep_33ZIBDmz66FcPG35FnsbM6Ie4X1",
        "url": "https://example.com/fax-webhooks",
        "description": "Sales inbox",
        "filter_types": ["fax_sent", "fax_received"],
        "channels": ["+12135550123"],
        "disabled": false,
        "created_at": "2026-08-31T15:11:00Z",
        "updated_at": "2026-08-31T15:11:00Z"
      }
    ],
    "next": null
  }
  ```

  ```json 400 theme={null}
  {
    "error": "bad_request",
    "description": "invalid_limit"
  }
  ```

  ```json 403 theme={null}
  {
    "error": "plan_not_eligible"
  }
  ```

  ```json 404 theme={null}
  {
    "error": "bad_request",
    "description": "application not found, enable webhooks in Fax.Plus integrations settings"
  }
  ```

  ```json 500 theme={null}
  {
    "error": "server_error",
    "description": "server_error"
  }
  ```
</ResponseExample>


## OpenAPI

````yaml get /webhooks
openapi: 3.0.1
info:
  title: Fax.Plus REST API
  description: >-
    This is the Fax.Plus API v3 developed for third party developers and
    organizations. In order to have a better coding experience with this API,
    let's quickly go through some points:<br /><br /> - This API assumes
    **/accounts** as an entry point with the base url of
    **https://restapi.fax.plus/v3**. <br /><br /> - This API treats all date and
    times sent to it in requests as **UTC**. Also, all dates and times returned
    in responses are in **UTC**<br /><br /> - Once you have an access_token, you
    can easily send a request to the resource server with the base url of
    **https://restapi.fax.plus/v3** to access your permitted resources. As an
    example to get the user's profile info you would send a request to
    **https://restapi.fax.plus/v3/accounts/self** when **Authorization** header
    is set to **Bearer YOUR_ACCESS_TOKEN** and custom header of
    **x-fax-clientid** is set to YOUR_CLIENT_ID
  version: 3.5.0
  contact:
    name: Fax.Plus
    email: info@fax.plus
    url: https://github.com/alohi
servers:
  - url: https://restapi.fax.plus/v3
  - url: /v3
security: []
paths:
  /webhooks:
    get:
      tags:
        - Webhooks
      summary: List webhook endpoints
      description: >-
        List webhook endpoints for this account. Optional `event` filter uses
        names (`fax_received`). Requires webhooks to be enabled in Integrations.
        (Permitted scopes: **fax:all:read**, **fax:webhook:read**)
      operationId: listWebhookEndpoints
      parameters:
        - name: event
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/WebhookFilterType'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
        - name: next
          in: query
          required: false
          schema:
            type: string
          description: Pagination cursor from a previous list response
      responses:
        '200':
          $ref: '#/components/responses/WebhookEndpointList'
        '400':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - oauth2:
            - all
        - personal_access_token:
            - fax:all:read
            - fax:webhook:read
components:
  schemas:
    WebhookFilterType:
      description: Webhook event type for /webhooks endpoints
      enum:
        - fax_received
        - fax_sent
        - fax_page_received
      type: string
    WebhookEndpointList:
      description: Page of webhook endpoints
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEndpoint'
        next:
          type: string
          nullable: true
      required:
        - data
      additionalProperties: false
      example:
        data:
          - id: ep_33ZIBDmz66FcPG35FnsbM6Ie4X1
            url: https://example.com/fax-webhooks
            description: Sales inbox
            filter_types:
              - fax_sent
              - fax_received
            channels:
              - '+12135550123'
            disabled: false
            created_at: '2026-08-31T15:11:00Z'
            updated_at: '2026-08-31T15:11:00Z'
        next: null
    Error:
      properties:
        description:
          type: string
        error:
          type: string
      additionalProperties: false
    WebhookEndpoint:
      description: Webhook endpoint as returned by list
      type: object
      properties:
        id:
          type: string
          example: ep_33ZIBDmz66FcPG35FnsbM6Ie4X1
        uid:
          type: string
          nullable: true
        url:
          type: string
        description:
          type: string
        filter_types:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/WebhookFilterType'
        channels:
          type: array
          nullable: true
          items:
            type: string
            description: >-
              Fax number in E.164 format. Matches fax from or to, including
              numbers you do not own.
        disabled:
          type: boolean
          nullable: true
        metadata:
          type: object
          additionalProperties:
            type: string
        rate_limit:
          type: integer
          nullable: true
        throttle_rate:
          type: integer
          nullable: true
        version:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - url
  responses:
    WebhookEndpointList:
      description: Page of webhook endpoints
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebhookEndpointList'
          example:
            data:
              - id: ep_33ZIBDmz66FcPG35FnsbM6Ie4X1
                url: https://example.com/fax-webhooks
                description: Sales inbox
                filter_types:
                  - fax_sent
                  - fax_received
                channels:
                  - '+12135550123'
                disabled: false
                created_at: '2026-08-31T15:11:00Z'
                updated_at: '2026-08-31T15:11:00Z'
            next: null
    Error:
      description: Error object in case there's a problem with given data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: invalid_user_id
            description: Invalid user id given
    NotFoundError:
      description: Requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: bad_request
            description: Requested resource was not found.
    ServerError:
      description: Error object in case there's a server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: internal_server_error
            description: An unexpected error happened, please contact support
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth2 Authorization Grant
      flows:
        authorizationCode:
          authorizationUrl: >-
            https://accounts.fax.plus/login?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost&scope=all
          tokenUrl: https://accounts.fax.plus/token
          refreshUrl: >-
            https://accounts.fax.plus/token?grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN
          scopes:
            all: >-
              for now when a user grants permission, all grants will be
              permitted
    personal_access_token:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Personal Access Token (PAT) is a Bearer token used for secure API calls.
        For direct API calls, the PAT is used in the Authorization header as
        'Bearer {PAT}'. For MCP usage, configure your PAT in your MCP client
        settings (e.g., in your IDE's MCP server configuration) - authentication
        will be handled automatically.

````