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

# List Webhooks

> Lists the webhooks configured on an account, optionally filtered by state

Lists the webhooks configured on an account, with their secrets masked. An account with no webhooks returns an empty array.

Pass `state=ACTIVE` or `state=INACTIVE` to list only the webhooks in that state, and omit it to list all of them.

The same webhooks are listed in the Developers tab of the [Yuno dashboard](/docs/webhooks/configure-webhooks).


## OpenAPI

````yaml openapi/webhooks/manage-webhooks.json GET /webhooks
openapi: 3.1.0
info:
  title: webhooks-manage-webhooks
  version: 1.0.0
servers:
  - url: https://api-sandbox.y.uno/v1
security:
  - sec0: []
    sec1: []
paths:
  /webhooks:
    get:
      summary: List Webhooks
      description: >-
        Returns the webhooks configured on an account, with their secrets
        masked. Filter by `state` to list only the active or the inactive ones.
      operationId: list-webhooks
      parameters:
        - name: account_id
          in: query
          required: true
          description: The unique identifier of the account the webhooks belong to.
          schema:
            type: string
            format: uuid
            example: 493e9374-510a-4201-9e09-de669d75f256
            x-default: 493e9374-510a-4201-9e09-de669d75f256
        - name: state
          in: query
          required: false
          description: >-
            Return only the webhooks in this state. Omit it to return all of
            them.
          schema:
            type: string
            enum:
              - ACTIVE
              - INACTIVE
            example: ACTIVE
      responses:
        '200':
          description: >-
            The webhooks configured on the account, or an empty array if it has
            none.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Webhook'
              example:
                - id: '12345'
                  account_id: 493e9374-510a-4201-9e09-de669d75f256
                  name: Production payments listener
                  state: ACTIVE
                  url: https://api.acme.com/yuno/webhooks
                  api_key: '***'
                  secret: '***'
                  hmac_client_secret: '***'
                  oauth2_authentication_url: null
                  oauth2_client_secret: null
                  oauth2_client_id: null
                  oauth2_grant_type: null
                  oauth2_scope: null
                  oauth2_authorization_name: null
                  oauth2_include_client_id: false
                  enrollment_triggers: []
                  payment_triggers:
                    - AUTHORIZE
                    - CAPTURE
                    - REFUND
                  report_triggers: []
                  subscription_triggers: null
                  onboarding_triggers: null
                  renewal_days: null
                  created_at: '2026-07-09T13:05:36.482913Z'
                  updated_at: '2026-07-09T13:05:36.482913Z'
                - id: '12346'
                  account_id: 493e9374-510a-4201-9e09-de669d75f256
                  name: Subscription renewals
                  state: INACTIVE
                  url: https://api.acme.com/yuno/subscriptions
                  api_key: '***'
                  secret: '***'
                  hmac_client_secret: null
                  oauth2_authentication_url: null
                  oauth2_client_secret: null
                  oauth2_client_id: null
                  oauth2_grant_type: null
                  oauth2_scope: null
                  oauth2_authorization_name: null
                  oauth2_include_client_id: false
                  enrollment_triggers: []
                  payment_triggers: []
                  report_triggers: []
                  subscription_triggers:
                    - CREATE
                    - CLOSE_TO_RENEWAL
                  onboarding_triggers: null
                  renewal_days: 5
                  created_at: '2026-07-10T09:41:12.204518Z'
                  updated_at: '2026-07-11T16:20:44.918330Z'
        '400':
          $ref: '#/components/responses/InvalidListRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '502':
          $ref: '#/components/responses/UpstreamError'
components:
  schemas:
    Webhook:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the webhook.
          example: '12345'
        account_id:
          type: string
          format: uuid
          description: The unique identifier of the account the webhook belongs to.
          example: 493e9374-510a-4201-9e09-de669d75f256
        name:
          type: string
          description: Your name for the webhook.
          example: Production payments listener
        state:
          type: string
          description: >-
            `ACTIVE` webhooks receive notifications, `INACTIVE` ones do not. A
            webhook starts out `ACTIVE`.
          enum:
            - ACTIVE
            - INACTIVE
          example: ACTIVE
        url:
          type: string
          description: The endpoint Yuno sends the notifications to.
          example: https://api.acme.com/yuno/webhooks
        api_key:
          type:
            - string
            - 'null'
          description: Masked as `***`, or `null` when you have not configured it.
          example: '***'
        secret:
          type:
            - string
            - 'null'
          description: Masked as `***`, or `null` when you have not configured it.
          example: '***'
        hmac_client_secret:
          type:
            - string
            - 'null'
          description: Masked as `***`, or `null` when you have not configured it.
          example: '***'
        oauth2_authentication_url:
          type:
            - string
            - 'null'
          description: Your token endpoint.
          example: https://api.acme.com/oauth/token
        oauth2_client_secret:
          type:
            - string
            - 'null'
          description: Masked as `***`, or `null` when you have not configured it.
          example: '***'
        oauth2_client_id:
          type:
            - string
            - 'null'
          description: The client identifier Yuno authenticates with.
          example: acme_client_id
        oauth2_grant_type:
          type:
            - string
            - 'null'
          description: The grant type Yuno requests the token with.
          example: client_credentials
        oauth2_scope:
          type:
            - string
            - 'null'
          description: The scope Yuno requests the token with.
          example: webhooks:write
        oauth2_authorization_name:
          type:
            - string
            - 'null'
          description: The header Yuno sends the token in.
          example: Authorization
        oauth2_include_client_id:
          type: boolean
          description: >-
            Whether Yuno also sends the client identifier as a header on the
            token request.
          example: true
        enrollment_triggers:
          type:
            - array
            - 'null'
          description: The enrollment events the webhook subscribes to.
          items:
            type: string
          example:
            - ENROLL
            - UNENROLL
        payment_triggers:
          type:
            - array
            - 'null'
          description: The payment events the webhook subscribes to.
          items:
            type: string
          example:
            - AUTHORIZE
            - CAPTURE
            - REFUND
        report_triggers:
          type:
            - array
            - 'null'
          description: The report events the webhook subscribes to.
          items:
            type: string
          example:
            - UPDATE
        subscription_triggers:
          type:
            - array
            - 'null'
          description: The subscription events the webhook subscribes to.
          items:
            type: string
          example:
            - CREATE
            - CLOSE_TO_RENEWAL
        onboarding_triggers:
          type:
            - array
            - 'null'
          description: The onboarding events the webhook subscribes to.
          items:
            type: string
          example:
            - CREATED
            - SUCCEEDED
        renewal_days:
          type:
            - integer
            - 'null'
          description: >-
            How many days before a renewal Yuno sends the `CLOSE_TO_RENEWAL`
            notification.
          example: 5
        created_at:
          type: string
          description: The date and time the webhook was created, in ISO 8601.
          example: '2026-07-09T13:05:36.482913Z'
          format: date-time
        updated_at:
          type: string
          description: >-
            The date and time the webhook was last updated, in ISO 8601. It
            matches `created_at` until you update the webhook for the first
            time.
          example: '2026-07-11T16:20:44.918330Z'
          format: date-time
    WebhookRequestError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
          enum:
            - WEBHOOK_INVALID_REQUEST
            - INVALID_ACCOUNT_ID
        messages:
          type: array
          description: Human-readable description of the error.
          items:
            type: string
    WebhookAuthError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
          enum:
            - NOT_AUTHENTICATED
            - INVALID_CREDENTIALS
        messages:
          type: array
          description: Human-readable description of the error.
          items:
            type: string
    WebhookUpstreamError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
          enum:
            - WEBHOOK_UPSTREAM_ERROR
        messages:
          type: array
          description: Human-readable description of the error.
          items:
            type: string
  responses:
    InvalidListRequest:
      description: >-
        The `account_id` is missing or invalid, or `state` is not `ACTIVE` or
        `INACTIVE`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebhookRequestError'
          examples:
            Missing account_id:
              value:
                code: WEBHOOK_INVALID_REQUEST
                messages:
                  - account_id is required.
            Invalid state:
              value:
                code: WEBHOOK_INVALID_REQUEST
                messages:
                  - state must be ACTIVE or INACTIVE.
            Invalid account_id:
              value:
                code: INVALID_ACCOUNT_ID
                messages:
                  - Account id is invalid
    Unauthorized:
      description: Your API credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebhookAuthError'
          examples:
            Not authenticated:
              value:
                code: NOT_AUTHENTICATED
                messages:
                  - Not authenticated
            Invalid credentials:
              value:
                code: INVALID_CREDENTIALS
                messages:
                  - Invalid Credentials
    UpstreamError:
      description: The webhook service is temporarily unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebhookUpstreamError'
          examples:
            Service unavailable:
              value:
                code: WEBHOOK_UPSTREAM_ERROR
                messages:
                  - The webhook service is temporarily unavailable.
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: public-api-key
      x-default: <Your public-api-key>
    sec1:
      type: apiKey
      in: header
      name: private-secret-key
      x-default: <Your private-secret-key>

````