openapi: 3.1.0
info:
  title: Webhook Internal API - v1beta1
  description: API for registering and managing HTTP webhooks and subscriptions.
  version: v1beta1
  contact: {}
  license:
    name: HPE License
    url: https://www.hpe.com/us/en/software/licensing.html
servers:
  - url: >-
      http://unified-events-registration-service.unified-events.svc.cluster.local:5000
tags:
  - name: Webhooks
    description: Everything about Webhooks
  - name: Subscriptions
    description: Everything about Subscriptions
security:
  - Bearer: []
paths:
  /internal-events/v1beta1/webhooks/{webhookId}:
    patch:
      tags:
        - Webhooks
      operationId: updateWebhookStatus
      summary: Update a webhook status by ID
      description: Update an existing webhook's status
      parameters:
        - name: webhookId
          in: path
          required: true
          description: Webhook ID
          schema:
            type: string
            format: uuid
            default: 0908777a-788f-45da-afb8-295c626e4d14
          examples:
            equals:
              summary: Example with specific webhook ID
              description: Update specific webhook
              value: 0908777a-788f-45da-afb8-295c626e4d14
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/WebhookRegistrationPatchInput'
      responses:
        '200':
          description: Webhook updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                invalid-query-params:
                  summary: Invalid query params
                  value:
                    errorCode: HPE_GL_ERROR_BAD_REQUEST
                    message: Invalid query params
                    debugId: 75d40213-6776-40ff-a959-89a7514ef7fc
                    httpStatusCode: 400
        '401':
          description: Unauthorized - Invalid JWT token in Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                invalid-token:
                  summary: Invalid Token Error
                  value:
                    errorCode: HPE_GL_ERROR_UNAUTHORIZED
                    message: Invalid JWT token in Request
                    debugId: 75d40213-6776-40ff-a959-89a7514ef7fc
                    httpStatusCode: 401
        '403':
          description: Forbidden - The operation is forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                invalid-permission:
                  summary: Invalid Permission Error
                  value:
                    errorCode: HPE_GL_ERROR_FORBIDDEN
                    message: Invalid Permission Error
                    debugId: 75d40213-6776-40ff-a959-89a7514ef7fc
                    httpStatusCode: 403
        '404':
          description: Bad Request, A webhook doesn't exist with the given ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                not-found:
                  summary: Not found error
                  value:
                    errorCode: HPE_GL_ERROR_NOT_FOUND
                    message: Webhook not found
                    debugId: 75d40213-6776-40ff-a959-89a7514ef7fc
                    httpStatusCode: 404
        '422':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                invalid-request-body:
                  summary: Invalid request body error
                  value:
                    errorCode: HPE_GL_EVENTS_INVALID_REQUEST_BODY
                    message: Invalid request body
                    debugId: 75d40213-6776-40ff-a959-89a7514ef7fc
                    httpStatusCode: 422
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Request limit per hour.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of requests left for the time window.
            X-RateLimit-Reset:
              schema:
                type: string
                format: date-time
              description: The UTC date/time at which the current rate limit window resets.
        '500':
          description: >-
            Unexpected Server Error, Please re-try and contact HPE Support if
            the error is not resolved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                unexpected-error:
                  value:
                    errorCode: HPE_GL_ERROR_INTERNAL_SERVER_ERROR
                    message: >-
                      Unexpected error occurred while retrieving webhook, if the
                      issue persists, Please contact HPE Support
                    debugId: 75d40213-6776-40ff-a959-89a7514ef7fc
                    httpStatusCode: 500
  /internal-events/v1beta1/subscriptions:
    get:
      tags:
        - Subscriptions
      operationId: getAllSubscriptions
      summary: Get all subscriptions
      description: >-
        Retrieves a list of subscriptions, organized in descending order based
        on their creation time. <br><br> **Pagination**: This endpoint
        exclusively supports offset-based pagination.
      parameters:
        - name: limit
          in: query
          description: >-
            Specifies the number of results to be returned. The default value is
            200.
          required: false
          schema:
            maximum: 200
            minimum: 1
            type: integer
            format: int64
            default: 200
        - name: offset
          in: query
          description: >-
            Specifies the zero-based resource offset to start the response from.
            The default value is 0.
          required: false
          schema:
            type: integer
            format: int64
            default: 0
            minimum: 0
      responses:
        '200':
          description: subscriptions retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalSusbcriptionResponseList'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                invalid-query-params:
                  summary: Invalid query params
                  value:
                    errorCode: HPE_GL_ERROR_BAD_REQUEST
                    message: Invalid query params
                    debugId: 75d40213-6776-40ff-a959-89a7514ef7fc
                    httpStatusCode: 400
        '401':
          description: Unauthorized - Invalid JWT token in Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                invalid-token:
                  summary: Invalid Token Error
                  value:
                    errorCode: HPE_GL_ERROR_UNAUTHORIZED
                    message: Invalid JWT token in Request
                    debugId: 75d40213-6776-40ff-a959-89a7514ef7fc
                    httpStatusCode: 401
        '403':
          description: Forbidden - The operation is forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                invalid-permission:
                  summary: Invalid Permission Error
                  value:
                    errorCode: HPE_GL_ERROR_FORBIDDEN
                    message: Invalid Permission Error
                    debugId: 75d40213-6776-40ff-a959-89a7514ef7fc
                    httpStatusCode: 403
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Request limit per hour.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of requests left for the time window.
            X-RateLimit-Reset:
              schema:
                type: string
                format: date-time
              description: The UTC date/time at which the current rate limit window resets.
        '500':
          description: >-
            Unexpected Server Error, Please re-try and contact HPE Support if
            the error is not resolved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                unexpected-error:
                  value:
                    errorCode: HPE_GL_ERROR_INTERNAL_SERVER_ERROR
                    message: >-
                      Unexpected error occurred while retrieving webhook, if the
                      issue persists, Please contact HPE Support
                    debugId: 75d40213-6776-40ff-a959-89a7514ef7fc
                    httpStatusCode: 500
components:
  securitySchemes:
    Bearer:
      description: >-
        Personal access token compliant with RFC8725 issued by the HPE GreenLake
        platform.
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    WebhookRegistrationPatchInput:
      type: object
      description: Contains fields that can be updated for an existing webhook
      required:
        - status
      properties:
        status:
          description: Controlled by System only
          type: string
          default: PENDING
          enum:
            - ACTIVE
            - WARNING
            - ERROR
          examples:
            - ERROR
    WebhookResponse:
      type: object
      description: The response schema for webhook operations.
      required:
        - id
        - type
        - createdAt
        - updatedAt
        - generation
        - paused
        - name
        - destination
        - hpePrincipal
        - authType
        - clientId
        - issuerUrl
        - createdBy
        - description
        - resourceUri
        - status
        - dualSecret
        - batching
      properties:
        id:
          type: string
          description: The unique identifier of the webhook.
          format: uuid
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
        type:
          type: string
          description: The type of the resource.
          const: events/webhook
        name:
          type: string
          description: The name of the webhook.
          examples:
            - License Notification
        description:
          type: string
          description: A brief description of the webhook.
          examples:
            - Webhook for receiving license notifications
        destination:
          type: string
          description: The URL where events will be sent.
          examples:
            - https://example.com/new-endpoint
        paused:
          description: >-
            Indicates whether the webhook is paused. `false` means the webhook
            is not paused.
          type: boolean
          default: false
          examples:
            - false
        status:
          description: Controlled by System only
          type: string
          default: PENDING
          enum:
            - ACTIVE
            - DISABLED
            - PENDING
            - WARNING
            - ERROR
          examples:
            - ACTIVE
        stateReason:
          type: string
          description: The reason for the current state of the webhook.
          examples:
            - Failure in Event Deliveries
            - HMAC validation failed. Please verify webhook secret.
            - 'Webhook URL unreachable. error: <errorMsg>'
            - 'Webhook Disabled by user: <hpePrincipalID>'
        resourceUri:
          type: string
          description: URI to the resource itself (i.e. a self link).
          examples:
            - /events/v1beta1/webhooks/123e4567-e89b-12d3-a456-426614174000
        generation:
          type: integer
          description: Monotonically increasing update counter.
          examples:
            - 1
        hpePrincipal:
          type: string
          description: Security principal subject notation.
          examples:
            - user:<opaque-global-id>
        createdBy:
          type: string
          description: The user that created the webhook.
        createdAt:
          type: string
          format: date-time
          description: The timestamp when the webhook was created.
        updatedAt:
          type: string
          format: date-time
          description: The timestamp when the webhook was last updated
        authType:
          type: string
          description: type of authentication (oauth,apikey)
          examples:
            - oauth
            - apikey
        clientId:
          type: string
          description: ClientId used for generating bearer token for verification
          examples:
            - a822f43a-9e72-4a04-8476-ad00422b987f
        issuerUrl:
          type: string
          description: The token generating url
          examples:
            - http://example.com'
        dualSecret:
          type: boolean
          description: Indicates whether the webhook uses dual secret authentication.
          default: false
          examples:
            - false
        batching:
          type: boolean
          description: Indicates whether the webhook uses batching.
          default: false
          examples:
            - false
    InternalSusbcriptionResponseList:
      type: object
      description: Outlines the details of a subscription response.
      required:
        - id
        - workspaceId
        - resourceUri
        - eventType
        - hpePrincipal
        - createdBy
        - createdAt
        - updatedBy
        - updatedAt
        - generation
        - status
      properties:
        id:
          type: string
          description: Unique identifier of the subscription.
          format: uuid
          examples:
            - 0908777a-788f-45da-afb8-295c626e4d14
        workspaceId:
          type: string
          format: uuid
          examples:
            - 0908777a-788f-45da-afb8-295c626e4d14
        resourceUri:
          type: string
          description: URI to the subscription.
          examples:
            - /events/v1beta1/subscriptions/3fa85f64-5717-4562-b3fc-2c963f66afa6
        eventType:
          type: string
          description: The eventType assosciated with subscriptions
        hpePrincipal:
          type: string
          description: Security principal subject notation.
          examples:
            - user:<opaque-global-id>
        createdBy:
          type: string
          description: The user that created the subscription.
        createdAt:
          type: string
          format: date-time
          description: The date and time the subscription is created.
        updatedBy:
          type: string
          description: The user that updated the subscription.
        updatedAt:
          type: string
          format: date-time
          description: The last date and time the subscription is updated.
        generation:
          type: integer
          minimum: 0
          description: >-
            Monotonically increasing update counter to track the subscription
            version.
          examples:
            - 1
        status:
          description: status of the webhook
          type: string
          default: enabled
          enum:
            - enabled
            - disabled
          examples:
            - enabled
        eventFilter:
          type: string
          description: >-
            The filter to apply to events. [Filtering
            Standard](https://developer.greenlake.hpe.com/docs/greenlake/standards/ratified/api/query_parameters/#filtering)
          examples:
            - createdAt lt 2021-05-12T07:20:00.00Z
    ApiError:
      type: object
      description: A generic error schema used across the API for error handling.
      required:
        - errorCode
        - message
        - debugId
        - httpStatusCode
      properties:
        httpStatusCode:
          type: integer
          description: HTTP equivalent status code
        message:
          type: string
          description: User-friendly error message
        debugId:
          type: string
          format: uuid
          description: Unique identifier for the instance of this error
        errorCode:
          type: string
          description: Unique identifier for the instance of this error
