openapi: 3.0.1
info:
  title: Webhooks
  version: 2.10.0
  description: REST API for webhooks management.
  contact:
    name: Tradevest GmbH
servers:
  - url: https://tvda-api.platform-test.tradevest.ai
    description: Test
security:
  - Bearer: []
tags:
  - name: Webhooks
    description: Webhooks
paths:
  /webhooks:
    get:
      summary: Get All Webhooks
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Webhook'
              examples:
                Example 1:
                  value:
                    - createdOn: '2019-08-24T14:15:22Z'
                      modifiedOn: '2019-08-24T14:15:22Z'
                      eventType: CUSTOMER_NOTIFICATION
                      url: https://client-address.de/e9c1a702ccab
                    - createdOn: '2019-08-24T14:15:22Z'
                      modifiedOn: '2019-08-24T14:15:22Z'
                      eventType: DOCUMENT_NOTIFICATION
                      url: https://client-address.de/2de0d16efb49
                      headers:
                        - name: api-key
                          value: secret-api-key
      operationId: get-webhooks
      x-operation-group: webhooks-query
      x-required-permissions: rs/webhooks/read
      tags:
        - Webhooks
      description: '> Get information about existing webhooks.'
    post:
      summary: Create or Update Webhook
      operationId: create-webhook
      x-operation-group: webhooks-command
      x-required-permissions: rs/webhooks/write
      tags:
        - Webhooks
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      description: '> Create webhook, replacing the webhook for this event type if one already exists. It is possible to create only one webhook per event.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookData'
            examples:
              Example 1:
                value:
                  eventType: CUSTOMER_NOTIFICATION
                  url: https://client-address.de/e9c1a702ccab
                  headers:
                    - name: api-key
                      value: secret-api-key
  /webhooks/{eventType}:
    parameters:
      - schema:
          type: string
        name: eventType
        in: path
        required: true
        description: Event type of webhook.
    delete:
      summary: Delete Webhook
      operationId: delete-webhook
      x-operation-group: webhooks-command
      x-required-permissions: rs/webhooks/write
      tags:
        - Webhooks
      responses:
        '200':
          description: Webhook deleted
      description: '> Delete webhook with given eventType.'
    get:
      summary: Get Webhook
      operationId: get-webhook
      x-operation-group: webhooks-query
      x-required-permissions: rs/webhooks/read
      tags:
        - Webhooks
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      description: '> Get webhook by eventType.'
  /webhooks-missing:
    get:
      summary: Get All Missing Webhooks
      tags:
        - Webhooks
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WebhookMissing'
      operationId: get-webhooks-missing
      description: Get all missing webhooks. This is an auxiliary endpoint to help avoid situations where a notification could be missed.
      x-operation-group: webhooks-query
      x-required-permissions: rs/webhooks/read
  /undelivered-webhooks:
    get:
      summary: Get Undelivered Webhooks
      description: Get undelivered webhooks to retry sending them. Undelivered webhooks will be kept in database for 30 days. After this time they may be removed. It is an auxiliary endpoint that helps to find webhooks that have not been delivered.
      operationId: get-undelivered-webhooks
      x-operation-group: webhooks-query
      x-required-permissions: rs/webhooks/read
      tags:
        - Webhooks
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/endDate'
        - $ref: '#/components/parameters/eventType'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UndeliveredWebhooks'
    post:
      summary: Mark Delivered Webhooks
      description: Mark the webhook with the specified id and all previous ones as delivered. They will no longer appear in the Get Undelivered Webhooks response.
      operationId: mark-delivered-webhooks
      x-operation-group: webhooks-command
      x-required-permissions: rs/webhooks/write
      tags:
        - Webhooks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkDeliveredWebhooksData'
      responses:
        '200':
          description: OK
components:
  schemas:
    Webhook:
      type: object
      properties:
        createdOn:
          type: string
          format: date-time
          readOnly: true
        modifiedOn:
          type: string
          format: date-time
          readOnly: true
        eventType:
          $ref: '#/components/schemas/EventTypeEnum'
        url:
          type: string
          description: The URL must be HTTPS.
        headers:
          type: array
          description: List of headers which should be sent to the webhook.
          maxItems: 5
          items:
            $ref: '#/components/schemas/Header'
      required:
        - createdOn
        - eventType
        - modifiedOn
        - url
      title: Webhook
      x-examples:
        Example 1:
          createdOn: '2019-08-24T14:15:22Z'
          modifiedOn: '2019-08-24T14:15:22Z'
          eventType: CUSTOMER_NOTIFICATION
          url: https://client-address.de/e9c1a702ccab
          headers:
            - name: api-key
              value: secret-api-key
    Header:
      title: Header
      type: object
      properties:
        name:
          type: string
          description: Name of the header which should be sent.
          pattern: ^\S+$
        value:
          type: string
          description: Value of the header which should be sent.
      required:
        - name
        - value
      x-examples:
        Example 1:
          name: api-key
          value: secret-api-key
    WebhookData:
      title: WebhookData
      type: object
      properties:
        eventType:
          $ref: '#/components/schemas/EventTypeEnum'
        url:
          type: string
          description: The URL must be HTTPS.
        headers:
          type: array
          description: List of headers which should be sent to the webhook.
          maxItems: 5
          items:
            $ref: '#/components/schemas/Header'
      required:
        - eventType
        - url
    WebhookMissing:
      title: WebhookMissing
      type: object
      required:
        - eventType
      properties:
        eventType:
          $ref: '#/components/schemas/EventTypeEnum'
    UndeliveredWebhook:
      title: UndeliveredWebhook
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the undelivered webhook.
        webhook:
          $ref: '#/components/schemas/Webhook'
        body:
          type: string
          description: The body of the webhook request.
        errorMessage:
          type: string
          description: Error message from the delivery attempt.
        createdOn:
          type: string
          format: date-time
        modifiedOn:
          type: string
          format: date-time
      required:
        - id
        - webhook
        - body
        - errorMessage
        - createdOn
        - modifiedOn
    UndeliveredWebhooks:
      title: UndeliveredWebhooks
      type: object
      properties:
        data:
          type: array
          description: Array of undelivered webhooks.
          items:
            $ref: '#/components/schemas/UndeliveredWebhook'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
        - data
        - pagination
    MarkDeliveredWebhooksData:
      title: MarkDeliveredWebhooksData
      type: object
      properties:
        undeliveredWebhookId:
          description: Id of the newest undelivered webhook to be marked as delivered. All older webhooks will also be marked.
          type: string
          format: uuid
      required:
        - undeliveredWebhookId
    EventTypeEnum:
      title: EventTypeEnum
      type: string
      enum:
        - CUSTOMER_NOTIFICATION
        - NATURAL_PERSON_NOTIFICATION
        - IDENTIFICATION_VERIFICATION_NOTIFICATION
        - DOCUMENT_NOTIFICATION
        - PARTNER_DOCUMENT_NOTIFICATION
        - ONBOARDING_NOTIFICATION
        - CUSTOMER_PRODUCT_NOTIFICATION
        - LEGAL_ENTITY_SEARCH_NOTIFICATION
        - LABELS_UPDATE_NOTIFICATION
        - TRANSFER_NOTIFICATION
        - DIGITAL_ASSET_ORDER_NOTIFICATION
        - PROXY_NOTIFICATION
        - BENEFICIAL_OWNER_NOTIFICATION
        - USER_NOTIFICATION
        - RE_TOKEN_PRICES
        - STRATEGY_NOTIFICATION
        - OFFBOARDING_NOTIFICATION
        - LEGAL_ENTITY_NOTIFICATION
        - LEGAL_REPRESENTATIVE_NOTIFICATION
        - TRADITIONAL_ASSET_ORDER_NOTIFICATION
        - TRADITIONAL_ASSET_ORDER_NOTIFICATION_V2
        - PARTNER_NOTIFICATION
        - JOINT_PERSON_NOTIFICATION
        - TAX_EXEMPTION_ORDER_NOTIFICATION
        - CORPORATE_ACTION_NOTIFICATION
        - SAVINGS_PLANS_NOTIFICATION
        - TOKENIZED_ASSET_ORDER_NOTIFICATION
        - SAVINGS_PLANS_ORDER_NOTIFICATION
        - WAWEX_EX_ANTE_DOCUMENT_READY_NOTIFICATION
        - TOKENIZED_CORPORATE_ACTION_NOTIFICATION
    ErrorDetailsExplanation:
      title: ErrorDetailsExplanation
      type: object
      properties:
        code:
          type: string
          maxLength: 255
        parameter:
          type: string
        message:
          type: string
      required:
        - code
        - message
    ErrorDetails:
      title: ErrorDetails
      type: object
      properties:
        field:
          type: string
          maxLength: 255
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetailsExplanation'
      required:
        - field
    ErrorMessage:
      title: ErrorMessage
      type: object
      properties:
        message:
          type: string
        responseType:
          type: string
        validationString:
          minLength: 1
          type: string
        requestId:
          type: string
        errorCode:
          type: string
          maxLength: 255
        errorDetails:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetails'
      required:
        - message
        - responseType
        - requestId
    Pagination:
      title: Pagination
      type: object
      properties:
        cursor:
          type: string
          description: String value used for pagination, which should be set in next page request.
        limit:
          type: integer
          description: Maximum number of returned items
      required:
        - cursor
        - limit
  parameters:
    limit:
      name: limit
      in: query
      description: Maximum number of items to return
      schema:
        type: integer
        example: 20
        default: 20
        minimum: 1
    cursor:
      name: cursor
      in: query
      description: String value used for pagination
      schema:
        type: string
    startDate:
      name: startDate
      in: query
      description: Beginning filter range of the webhook notification that was undelivered. This is not filtering on the webhook creation date in the webhook object.
      schema:
        type: string
        format: date-time
        example: '2019-04-12T23:20:50.52Z'
    endDate:
      name: endDate
      in: query
      description: End filter range of the webhook notification that was undelivered. This is not filtering on the webhook creation date in the webhook object.
      schema:
        type: string
        format: date-time
        example: '2019-05-12T23:20:50.52Z'
    eventType:
      name: eventType
      in: query
      description: Event type of webhook.
      schema:
        $ref: '#/components/schemas/EventTypeEnum'
  securitySchemes:
    Bearer:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth2/token
          scopes: {}
x-tagGroups:
  - name: Webhooks
    tags:
      - Webhooks
