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

# List Webhooks

> List the client's webhooks with their subscribed events. The signing secret is never returned.

[Subtotal Connector tool: list\_webhooks](/docs/connector/tools.md#list_webhooks)

## Access

Call this endpoint with your API key, or with a [Subtotal Connector](/docs/connector/introduction.md) OAuth token that includes `webhooks:read`. A token without `webhooks:read` receives `403 insufficient_scope`. [Partner app](/docs/partner-apps/introduction.md#fixed-permissions) tokens don't include it.

## Example

```bash theme={null}
curl 'https://api.subtotal.com/webhooks' \
  --header "x-api-key: $SUBTOTAL_API_KEY"
```

```json theme={null}
{
  "webhooks": [
    {
      "webhook_id": "01JA7Q2W3E4R5T6Y7U8I9O0P1A",
      "name": "Order sync",
      "url": "https://hooks.example.com/subtotal",
      "is_active": true,
      "event_types": ["connection.activated", "purchase.created"],
      "receive_simulated_events": false,
      "purchase_date_start": null,
      "purchase_date_end": null,
      "created_at": "2026-10-14T17:02:11Z"
    }
  ]
}
```

The signing secret is never returned here. It's shown once, when the webhook is [created](/docs/api-reference/webhooks/create-webhook.md).


## OpenAPI

````yaml get /webhooks
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security: []
paths:
  /webhooks:
    get:
      tags:
        - webhooks
      summary: List Webhooks
      description: >-
        List the client's webhooks with their subscribed events. The signing
        secret is never returned.
      operationId: list_webhooks_webhooks_get
      parameters:
        - name: authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
        - name: x-api-key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    WebhookListResponse:
      properties:
        webhooks:
          items:
            $ref: '#/components/schemas/WebhookItem'
          type: array
          title: Webhooks
      type: object
      required:
        - webhooks
      title: WebhookListResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    WebhookItem:
      properties:
        webhook_id:
          type: string
          title: Webhook Id
        name:
          type: string
          title: Name
        url:
          type: string
          title: Url
        is_active:
          type: boolean
          title: Is Active
        event_types:
          items:
            type: string
          type: array
          title: Event Types
          description: Subscribed event names, e.g. `purchase.created`.
        receive_simulated_events:
          type: boolean
          title: Receive Simulated Events
          description: Also deliver events from the simulator.
        purchase_date_start:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Purchase Date Start
          description: Only purchases on or after this date; null = unbounded.
        purchase_date_end:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Purchase Date End
          description: Only purchases on or before this date; null = unbounded.
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - webhook_id
        - name
        - url
        - is_active
        - event_types
        - receive_simulated_events
        - purchase_date_start
        - purchase_date_end
        - created_at
      title: WebhookItem
      description: A client webhook. The signing secret is never part of this shape.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````

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