openapi: 3.0.0
paths:
  /invoices/{id}/subscribe:
    parameters:
    - name: id
      in: path
      required: true
      description: The id of the invoice about which you want to receive notifications
      schema:
        $ref: '#/components/schemas/invoiceId'
    post:
      summary: Subscription to events about given invoice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                token:
                  type: string
              required:
              - url
              - token
      responses:
        '202':
          description: 'Successfully subscribed to events about given invoice'
          content:
            text/plain:
              examples:
                ok:
                  value: 'ok'

      callbacks:
        actions:
          '{$request.body#/url}?token={$request.body#/token}':
            post:
              summary: 'Receive notification about certain invoice'
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/notification'
              responses:
                200:
                  description: 'Notification successfully processed'
                  content:
                    text/plain:
                      examples:
                        ok:
                          value: 'ok'
components:
  schemas:
    invoiceId:
      type: integer
      format: int64
    notification:
      type: object
      properties:
        invoiceId:
          $ref: "#/components/schemas/invoiceId"
        action:
          type: string
          enum:
          - paid
          - expired
          - failure
      required:
      - invoiceId
      - action