accountAPI-eventNotificationWebhook.yaml

openapi: 3.0.0
info:
  version: 6.0.0
  title: event-notification webhook
  description: |
    This is the specification of the 'event-notification' webhook.
  contact:
    email: info@common-api.ch
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://webhook-notification.common-api.ch
externalDocs:
  description: Find out more about SFTI API specifications.
  url: https://www.common-api.ch
tags:
  - name: event notification webhook
    description: Event notification webhook operations.
security: []
paths:
  /event-notifications:
    post:
      tags:
        - event notification webhook
      summary: Push notification towards service users
      description: Push notifications for subscribed event notifications.
      operationId: postEventNotification
      parameters:
        - $ref: '#/components/parameters/client_id'
        - $ref: '#/components/parameters/correlation'
        - $ref: '#/components/parameters/agent'
        - $ref: '#/components/parameters/target_id'
        - $ref: '#/components/parameters/psu_ip'
        - $ref: '#/components/parameters/psu_user_agent'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventNotification'
      responses:
        '202':
          description: Notification accepted.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
        '400':
          $ref: '#/components/responses/standard400'
        '404':
          $ref: '#/components/responses/standard404'
        '429':
          $ref: '#/components/responses/standard429'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'
        '504':
          $ref: '#/components/responses/standard504'
components:
  schemas:
    CommonErrorResponse:
      title: Common Error Response
      description: The common error response object.
      type: object
      required:
        - detail
        - title
        - type
      properties:
        detail:
          type: string
          description: The details about the common error response.
          example: Detailed problem description with respect to the current request
        title:
          type: string
          description: The title of the common error response.
          example: This is the general problem description
        type:
          $ref: '#/components/schemas/CommonErrorType'
        instance:
          type: string
          description: The path to the corresponding resource.
          example: path/to/corresponding/resource
        status:
          type: integer
          format: int32
          description: The HTTP status code generated by the origin server.
          example: 404
    CommonErrorType:
      title: Common Error Type
      description: Error Types for CommonErrorResponse.
      type: string
      enum:
        - /problems/INVALID_PAYLOAD
        - /problems/MALFORMED_PAYLOAD
        - /problems/INVALID_TOKEN
        - /problems/EXPIRED_TOKEN
        - /problems/INSUFFICIENT_PRIVILEGES
        - /problems/NO_ACCESS_TO_RESOURCE
        - /problems/RESOURCE_DOES_NOT_EXIST
        - /problems/RESOURCE_NOT_READY
        - /problems/RESOURCE_TOO_LARGE
        - /problems/WRONG_METHOD
        - /problems/OPERATION_NOT_ALLOWED
        - /problems/TECHNICAL_ERROR
        - /problems/NOT_IMPLEMENTED
        - /problems/SERVICE_UNAVAILABLE
      example: /problems/TECHNICAL_ERROR
    EventNotification:
      description: Schema of an event notification entity.
      type: object
      required:
        - eventSubscriptionId
        - eventType
        - id
        - resourceLink
      properties:
        eventSubscriptionId:
          type: string
          description: Id of the subscription that caused the event to be triggered.
          readOnly: true
          maxLength: 36
          example: 7c5f40fc-1b29-4263-a2dd-e127a22a947f
        eventType:
          $ref: '#/components/schemas/EventType'
        id:
          type: string
          description: Unique and unambiguous identification (i.e. UUID) of the event subscription.
          example: 120066c9-58a1-432b-aa60-712fae7f143e
        resourceLink:
          type: string
          description: |
            The resourceLink is an absolute or relative URL reference to the specific resource or object that triggered the webhook event.
            This link provides immediate access to the full details of the affected item in the source system.
          example: /accounts/e6751a48-0819-4482-98a4-760453ba770d
        creationDateTime:
          type: string
          format: date-time
          description: Timestamp of the creation of the event notification.
          example: 2022-10-26T07:58:30.996+0100
        version:
          type: string
          description: Version of the notification schema.
          example: '1.0'
    EventType:
      description: Event type the subscription should apply to AND reason why a notification is sent.
      type: string
      enum:
        - accounts:listUpdated
      example: accounts:listUpdated
  responses:
    standard400:
      headers:
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: |
        Bad Request - The format of the request was invalid.

        Examples:
        - InvalidPayload:
        type: /problems/INVALID_PAYLOAD
        title: Payload does not comply with API specification
        detail: Malformed JSON
        instance: path/to/corresponding/resource

        - InvalidParameter:
        type: /problems/INVALID_PAYLOAD
        title: Invalid parameter values have been detected
        detail: Sent data could not be processed
        instance: path/to/corresponding/resource

        - MissingId:
        type: /problems/INVALID_PAYLOAD
        title: The payload was not valid
        detail: ID is missing
        instance: path/to/corresponding/resource
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
    standard404:
      headers:
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: |
        Not Found - Either the endpoint does not exist or a requested resource is not
        yet available (e.g., account statements)

        Examples:
        - InvalidAccounts:
        type: /problems/INSUFFICIENT_PRIVILEGES
        title: Insufficient privileges to access resource
        detail: The provided token does not grant access to the requested account
        instance: path/to/corresponding/resource

        - WrongEndpointUrl:
        type: /problems/TECHNICAL_ERROR
        title: URL not found
        detail: The requested endpoint does not exist
        instance: path/to/corresponding/resource

        - NoIntradayDataSupported:
        type: /problems/NOT_IMPLEMENTED
        title: Feature is not implemented
        detail: This interface does not support intraday data
        instance: path/to/corresponding/resource
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
    standard429:
      headers:
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: Too many requests - The user has sent too many requests in a given amount of time.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
    standard500:
      headers:
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: |
        Internal Server Error - The server encountered an unexpected condition that
        prevented it from fulfilling the request.

        Examples:
        - TechnicalServerError:
        type: /problems/TECHNICAL_ERROR
        title: Technical error on server side
        detail: Processing yielded a technical error
        instance: path/to/corresponding/resource

        - ResourceTooLarge:
        type: /problems/RESOURCE_TOO_LARGE
        title: Generated resource was too large
        detail: The generated resource exceeded the size limit
        instance: path/to/corresponding/resource
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
    standard501:
      headers:
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: |
        Not Implemented - The server does not support the functionality required to fulfill the request.

        Examples:
        - EndpointNotImplemented:
        type: /problems/NOT_IMPLEMENTED
        title: Target endpoint is not implemented
        detail: This endpoint is not implemented
        instance: path/to/corresponding/resource
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
    standard503:
      headers:
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: Service Unavailable - The server is currently unable to handle the request due to a temporary overload or scheduled maintenance.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
    standard504:
      headers:
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: Gateway Timeout - The server did not get a response in time that it needed in order to complete the request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
  parameters:
    agent:
      in: header
      name: User-Agent
      description: Name and version of the of the Service User software.
      required: true
      schema:
        type: string
    client_id:
      in: header
      name: X-CorAPI-Client-ID
      description: ID of the Service User forwarded to the Service Provider.
      required: true
      schema:
        type: string
    correlation:
      in: header
      name: X-Correlation-ID
      description: Unique ID (defined by the caller) which will be reflected back in the response.
      required: true
      schema:
        type: string
        maxLength: 64
        pattern: ^[A-Za-z0-9\-._#{}]{5,64}$
    psu_ip:
      in: header
      name: X-PSU-IP-Address
      description: IP address of the user initiating the operation or AUTO for system triggered processes.
      required: true
      schema:
        type: string
    psu_user_agent:
      in: header
      name: X-PSU-User-Agent
      description: User agent of the user initiating the operation or AUTO for system triggered processes.
      required: true
      schema:
        type: string
    target_id:
      in: header
      name: X-CorAPI-Target-ID
      description: ID that identifies the Service Provider.
      required: true
      schema:
        type: string
  headers:
    Content-Language:
      description: Response language - always en.
      schema:
        type: string
    X-Correlation-ID:
      description: Service User defined ID from request to correlate HTTP requests between a Service User and a Service Provider.
      schema:
        type: string
        maxLength: 64
        pattern: ^[A-Za-z0-9\-._#{}]{5,64}$
        example: f058ebd6-02f7-4d3f-942e-904344e8cde5