openapi.yaml

openapi: 3.0.3
info:
  title: Webhooks
  version: WEBHOOKS_VERSION
paths:
  /configs:
    get:
      summary: Get many configs
      description: Sorted by updated date descending
      operationId: getManyConfigs
      tags:
        - webhooks.v1
      parameters:
        - name: id
          in: query
          description: Optional filter by Config ID
          required: false
          schema:
            type: string
            example: 4997257d-dfb6-445b-929c-cbe2ab182818
        - name: endpoint
          in: query
          description: Optional filter by endpoint URL
          required: false
          schema:
            type: string
            example: https://example.com
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - Authorization:
            - webhooks:read
    post:
      summary: Insert a new config
      description: >
        Insert a new webhooks config.


        The endpoint should be a valid https URL and be unique.


        The secret is the endpoint's verification secret.

        If not passed or empty, a secret is automatically generated.

        The format is a random string of bytes of size 24, base64 encoded.
        (larger size after encoding)


        All eventTypes are converted to lower-case when inserted.
      operationId: insertConfig
      tags:
        - webhooks.v1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigUser'
        required: true
      responses:
        '200':
          description: Config created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - Authorization:
            - webhooks:write
  /configs/{id}:
    delete:
      summary: Delete one config
      description: Delete a webhooks config by ID.
      operationId: deleteConfig
      tags:
        - webhooks.v1
      parameters:
        - name: id
          in: path
          description: Config ID
          required: true
          schema:
            type: string
            example: 4997257d-dfb6-445b-929c-cbe2ab182818
      responses:
        '200':
          description: Config successfully deleted.
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - Authorization:
            - webhooks:write
  /configs/{id}/test:
    get:
      summary: Test one config
      description: Test a config by sending a webhook to its endpoint.
      operationId: testConfig
      tags:
        - webhooks.v1
      parameters:
        - name: id
          in: path
          description: Config ID
          required: true
          schema:
            type: string
            example: 4997257d-dfb6-445b-929c-cbe2ab182818
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttemptResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - Authorization:
            - webhooks:read
  /configs/{id}/activate:
    put:
      summary: Activate one config
      description: >-
        Activate a webhooks config by ID, to start receiving webhooks to its
        endpoint.
      operationId: activateConfig
      tags:
        - webhooks.v1
      parameters:
        - name: id
          in: path
          description: Config ID
          required: true
          schema:
            type: string
            example: 4997257d-dfb6-445b-929c-cbe2ab182818
      responses:
        '200':
          description: Config successfully activated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - Authorization:
            - webhooks:write
  /configs/{id}/deactivate:
    put:
      summary: Deactivate one config
      description: >-
        Deactivate a webhooks config by ID, to stop receiving webhooks to its
        endpoint.
      operationId: deactivateConfig
      tags:
        - webhooks.v1
      parameters:
        - name: id
          in: path
          description: Config ID
          required: true
          schema:
            type: string
            example: 4997257d-dfb6-445b-929c-cbe2ab182818
      responses:
        '200':
          description: Config successfully deactivated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - Authorization:
            - webhooks:write
  /configs/{id}/secret/change:
    put:
      summary: Change the signing secret of a config
      description: >
        Change the signing secret of the endpoint of a webhooks config.


        If not passed or empty, a secret is automatically generated.

        The format is a random string of bytes of size 24, base64 encoded.
        (larger size after encoding)
      operationId: changeConfigSecret
      tags:
        - webhooks.v1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigChangeSecret'
      parameters:
        - name: id
          in: path
          description: Config ID
          required: true
          schema:
            type: string
            example: 4997257d-dfb6-445b-929c-cbe2ab182818
      responses:
        '200':
          description: Secret successfully changed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - Authorization:
            - webhooks:write
components:
  schemas:
    ConfigUser:
      type: object
      required:
        - endpoint
        - eventTypes
      properties:
        name:
          type: string
          example: customer_payment
        endpoint:
          type: string
          example: https://example.com
        secret:
          type: string
          example: V0bivxRWveaoz08afqjU6Ko/jwO0Cb+3
        eventTypes:
          type: array
          items:
            type: string
            example: TYPE1
          example:
            - TYPE1
            - TYPE2
    ConfigsResponse:
      type: object
      required:
        - cursor
      properties:
        cursor:
          allOf:
            - $ref: '#/components/schemas/Cursor'
            - properties:
                data:
                  items:
                    $ref: '#/components/schemas/WebhooksConfig'
                  type: array
              type: object
              required:
                - data
    Cursor:
      type: object
      required:
        - hasMore
        - data
      properties:
        hasMore:
          type: boolean
          example: false
        data:
          type: array
          items:
            $ref: '#/components/schemas/WebhooksConfig'
    ConfigResponse:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/WebhooksConfig'
    WebhooksConfig:
      properties:
        id:
          type: string
          format: uuid
        endpoint:
          type: string
          example: https://example.com
        secret:
          type: string
          example: V0bivxRWveaoz08afqjU6Ko/jwO0Cb+3
        eventTypes:
          type: array
          items:
            type: string
            example: TYPE1
          example:
            - TYPE1
            - TYPE2
        active:
          type: boolean
          example: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - endpoint
        - secret
        - eventTypes
        - active
        - createdAt
        - updatedAt
    ConfigChangeSecret:
      type: object
      properties:
        secret:
          type: string
          example: V0bivxRWveaoz08afqjU6Ko/jwO0Cb+3
      required:
        - secret
    AttemptResponse:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/Attempt'
    Attempt:
      properties:
        id:
          type: string
          format: uuid
        webhookID:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        config:
          $ref: '#/components/schemas/WebhooksConfig'
        payload:
          type: string
          example: '{"data":"test"}'
        statusCode:
          type: integer
          example: 200
        retryAttempt:
          type: integer
          example: 1
        status:
          type: string
          example: success
        nextRetryAfter:
          type: string
          format: date-time
      required:
        - id
        - webhookID
        - createdAt
        - updatedAt
        - config
        - payload
        - statusCode
        - retryAttempt
        - status
    ErrorResponse:
      type: object
      required:
        - errorCode
        - errorMessage
      properties:
        errorCode:
          $ref: '#/components/schemas/ErrorsEnum'
        errorMessage:
          type: string
          example: '[VALIDATION] invalid ''cursor'' query param'
        details:
          type: string
          example: >-
            https://play.numscript.org/?payload=eyJlcnJvciI6ImFjY291bnQgaGFkIGluc3VmZmljaWVudCBmdW5kcyJ9
    ErrorsEnum:
      type: string
      enum:
        - INTERNAL
        - VALIDATION
        - NOT_FOUND
      example: VALIDATION