openapi: 3.1.0
info:
  title: Credentially Public Compliance-packages Subscriptions API
  description: Public API Proxy with Rate Limiting and Audit
  version: 2.0.0
servers:
- url: https://app.credentially.io/gateway
  description: Generated server url
tags:
- name: Subscriptions
  description: API for managing webhook callback subscriptions
paths:
  /subscriptions:
    get:
      tags:
      - Subscriptions
      summary: Get all webhook subscriptions for this org
      operationId: getSubscriptions
      responses:
        '200':
          description: List of subscriptions retrieved successfully
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
      security:
      - bearer-key: []
    post:
      tags:
      - Subscriptions
      summary: Create a new webhook subscription
      operationId: createSubscription
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionRequest'
        required: true
      responses:
        '201':
          description: Subscription created successfully
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '400':
          description: Invalid input
      security:
      - bearer-key: []
  /subscriptions/{id}:
    delete:
      tags:
      - Subscriptions
      summary: Delete a webhook subscription
      operationId: deleteSubscription
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Subscription deleted successfully
        '404':
          description: Subscription not found
      security:
      - bearer-key: []
components:
  schemas:
    SubscriptionResponse:
      type: object
      description: Webhook subscription returned from the API
      properties:
        id:
          type: string
          format: uuid
        callbackUrl:
          type: string
        webhookName:
          type: string
        eventTypes:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
    CreateSubscriptionRequest:
      type: object
      description: Request object for creating a subscription
      properties:
        callbackUrl:
          type: string
          description: The URL to receive webhook events
          example: https://api.example.com/callbacks
          maxLength: 500
          minLength: 0
          pattern: ^https?://.+
        webhookName:
          type: string
          description: Identifiable name for this webhook subscription
          maxLength: 50
          minLength: 3
          pattern: ^[a-zA-Z0-9_-]+$
        password:
          type: string
          description: Password for Basic Auth on the callback URL
          maxLength: 50
          minLength: 8
        eventTypes:
          type: array
          description: Set of event types to subscribe to
          example:
          - PROFILE_COMPLIANCE_STATUS_CHANGED
          - PROFILE_DBS_STATUS_CHANGED
          items:
            type: string
            minLength: 1
          minItems: 1
          uniqueItems: true
      required:
      - callbackUrl
      - eventTypes
      - password
      - webhookName
  securitySchemes:
    bearer-key:
      type: http
      scheme: bearer
      bearerFormat: JWT