openapi: 3.0.3
info:
  title: Remote Request Hook API
  description: |
    <a href="/openapi/ui/remote-request-hook-openapi.yaml" target="_blank" download="remote-request-hook-openapi.yaml"><button>Download OpenAPI Specification</button></a>

    A **Remote Request Hook** receive approvals request from Witboost such that they can be forwarded to third-party ticketing systems.

    As an example, with the Remote Request Hook, you can handle Access Control requests from outside Witboost.
  version: '0.1.0'
tags:
  - name: RemoteRequestHook
paths:
  '/approval-requests':
    post:
      tags:
        - RemoteRequestHook
      summary: Send approval request
      description: Receive a request from witboost about an ongoing action started by a user that requires a third-party interaction on your end
      parameters:
        - in: header
          name: X-Request-ID
          description: A unique identifier for the request that can be used to trace the request in the logs.
          schema:
            type: string
            format: uuid
          required: true
          examples:
            sampleRequestId:
              value: '6bba34a3-173e-4100-9ccb-5b63035cc86a'
      requestBody:
        description: An object containing all the input data received by the action where the remote request hook is attached
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
            examples:
              exampleRequest:
                value:
                  respondToUrl: 'http://my-instance.witboost.com/api/actionHandler/123456'
                  fields:
                    identities:
                      - john.doe_company.com
                    verb: grant
                    motivation: 'I need access to this resource'
                    domain: 'finance'
                    role: 'data_engineer'
        required: true
      responses:
        202:
          description: Declares that you accepted the remote request and you are asynchronously working on it, or that the request has been registered into an external system and it is waiting for a user interaction
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Response'
                  - $ref: '#/components/schemas/TraceableResponse'
              examples:
                standard:
                  value:
                    hookInfo:
                      status: 'accepted'
                      message: 'request has been accepted on the external system'
                traceable:
                  value:
                    hookInfo:
                      status: 'accepted'
                      message: 'request has been accepted on the external system'
                      tracking:
                        id: '123456'
                        url: 'https://external-system.com/requests/123456'

        400:
          description: A malformed input has been received
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                malformedInputError:
                  value:
                    error:
                      message: 'The input data is malformed'
        401:
          description: Unauthorized sender. For services that implements an authorization mechanism, this is the error code to answer in case of misconfigurations or failed authorization attempts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorizedError:
                  value:
                    error:
                      message: 'Unauthorized sender'
        500:
          description: Internal server error during the request processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                internalError:
                  value:
                    error:
                      message: 'Internal server error'
components:
  schemas:
    Request:
      type: object
      required:
        - respondToUrl
        - fields
      properties:
        respondToUrl:
          type: string
          description: URL to be contacted to notify that the hook is completed. This represents the fact that the third-party interaction has been performed on your end. e.g. An access request that has been accepted on your dedicated platform
        fields:
          type: object
          description: A free-form object containing all the action's input data coming from witboost
    Response:
      type: object
      required:
        - hookInfo
      properties:
        hookInfo:
          type: object
          description: A free-form object that will be stored together as the hook's response data

    TraceableResponse:
      type: object
      required:
        - hookInfo
      properties:
        hookInfo:
          type: object
          description: A free-form object that will be stored as the hook's response data with an optional reserved field name for tracking information
          properties:
            tracking:
              type: object
              description: A reserved field for any available tracking information for the users to check the status of their request in the external system
              properties:
                id:
                  type: string
                  description: An optional id of the request on the external system, this is helpful if the external system is known to witboost and can reconstruct the URL that a user should visit. Or when it's not possible to provide a viewable URL for the user to check the status of the request.
                url:
                  type: string
                  description: An optional URL of the request on the external system, it should link to an external system that can show to the users the status of their requests
          additionalProperties: true

    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
          properties:
            message:
              type: string
              description: An informative user-friendly message that informs about the request delivery failure. This message is shown to the user in the Witboost UI.
            details:
              type: string
              description: An informative message that can be used to debug the error through witboost logs.
          additionalProperties: true