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

# List Webhook Endpoints

> Retrieve all webhook endpoints configured for your group

<Note>
  This endpoint requires HMAC-SHA256 authentication. See [Authentication](../../docs/terminal-gateway/authentication) for signature computation details.
</Note>

## Response Details

The response includes all webhook endpoints configured for your group, including:

* **Active endpoints** that are receiving webhooks
* **Disabled endpoints** that have been paused but not deleted

<Tip>
  The webhook signing `secret` is not included in list responses. It is only returned once during endpoint creation.
</Tip>

## Endpoint Status

| Status     | Description                                   |
| ---------- | --------------------------------------------- |
| `active`   | Endpoint is receiving webhook deliveries      |
| `disabled` | Endpoint is paused; no webhooks are delivered |


## OpenAPI

````yaml api-reference/terminal-gateway/openapi.json GET /v1/webhooks/endpoints
openapi: 3.1.0
info:
  title: Terminal Gateway HTTP API
  version: 1.0.0
  description: >-
    HTTP API for POS-to-terminal communication. Enables payment processing
    through connected terminals.
  contact:
    name: Modulus Labs Support
    email: support@moduluslabs.io
servers:
  - url: https://your-endpoint.moduluslabs.io
    description: >-
      Your provisioned Terminal Gateway API endpoint. Contact
      support@moduluslabs.io to obtain your URL and credentials.
security:
  - hmacAuth: []
tags:
  - name: Terminals
    description: Terminal discovery and management
  - name: Payments
    description: Payment processing
  - name: Transactions
    description: Transaction status and reconciliation
  - name: Webhooks
    description: Webhook endpoint management for asynchronous payment notifications
paths:
  /v1/webhooks/endpoints:
    get:
      tags:
        - Webhooks
      summary: List Webhook Endpoints
      description: Retrieve all webhook endpoints configured for your group.
      operationId: listWebhookEndpoints
      responses:
        '200':
          description: List of webhook endpoints
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWebhookEndpointsResponse'
              example:
                endpoints:
                  - endpointId: wh_01HQ3K4M5N6P7R8S9T0UVWXYZ
                    url: https://api.yourcompany.com/webhooks/payments
                    events:
                      - payment.completed
                      - payment.failed
                      - payment.cancelled
                      - payment.timeout
                    description: Production payment notifications
                    status: active
                    metadata:
                      environment: production
                    createdAt: '2024-01-15T10:30:00.000Z'
                    updatedAt: '2024-01-15T10:30:00.000Z'
                count: 1
                timestamp: '2024-01-15T10:35:00.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    ListWebhookEndpointsResponse:
      type: object
      required:
        - endpoints
        - count
        - timestamp
      properties:
        endpoints:
          type: array
          description: List of webhook endpoints
          items:
            $ref: '#/components/schemas/WebhookEndpoint'
        count:
          type: integer
          description: Total number of endpoints
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the response
    WebhookEndpoint:
      type: object
      required:
        - endpointId
        - url
        - events
        - status
        - createdAt
        - updatedAt
      properties:
        endpointId:
          type: string
          description: Unique identifier for the webhook endpoint.
        url:
          type: string
          format: uri
          description: The HTTPS URL where webhook payloads are delivered.
        events:
          type: array
          items:
            type: string
            enum:
              - payment.completed
              - payment.failed
              - payment.cancelled
              - payment.timeout
          description: Event types this endpoint is subscribed to.
        description:
          type: string
          description: Human-readable description for this endpoint.
        status:
          type: string
          enum:
            - active
            - disabled
          description: Endpoint status.
        metadata:
          type: object
          description: Custom key-value pairs associated with this endpoint.
          additionalProperties: true
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the endpoint was created.
        updatedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last update.
    Error:
      type: object
      required:
        - error
        - timestamp
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Error code
            message:
              type: string
              description: Human-readable error message
            details:
              type: object
              description: Additional error details
              additionalProperties: true
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp
        requestId:
          type: string
          description: Request identifier for debugging
        transactionId:
          type: string
          description: Transaction ID if applicable
  responses:
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            unauthorized:
              summary: Invalid API key
              value:
                error:
                  code: UNAUTHORIZED
                  message: Missing or invalid API key
                timestamp: '2024-01-15T10:40:00.000Z'
            invalidSignature:
              summary: Invalid signature
              value:
                error:
                  code: INVALID_SIGNATURE
                  message: HMAC signature verification failed
                timestamp: '2024-01-15T10:40:00.000Z'
            timestampExpired:
              summary: Timestamp expired
              value:
                error:
                  code: TIMESTAMP_EXPIRED
                  message: Request timestamp outside 5-minute window
                timestamp: '2024-01-15T10:40:00.000Z'
    Forbidden:
      description: Access denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: GROUP_MISMATCH
              message: Resource belongs to a different group
            timestamp: '2024-01-15T10:40:00.000Z'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_ERROR
              message: Unexpected server error
            timestamp: '2024-01-15T10:40:00.000Z'
  securitySchemes:
    hmacAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        HMAC-SHA256 authentication. Requires three headers: x-api-key (your API
        key), x-timestamp (ISO 8601 timestamp), and x-signature (Base64-encoded
        HMAC-SHA256 signature). See Authentication documentation for signature
        computation.

````