FF-107: Webhooks (#45)

* added webhooks

* changed webhook api ref

* added identityID to webhook functions

* minor

* fixed

* refixed

* fixed

api/wallet/spec/definitions/DestinationsTopic.yaml

@@ -0,0 +1,18 @@
+description: |
+  Область охвата, включающая события по приёмникам денежных средств
+  в рамках определённого кошелька
+allOf:
+  - $ref: '#/definitions/WebhookScope'
+  - type: object
+    required:
+      - eventTypes
+    properties:
+      eventTypes:
+        description: Набор типов событий приёмника денежных средств, о которых следует оповещать
+        type: array
+        items:
+          type: string
+          enum:
+            - DestinationCreated
+            - DestinationUnauthorized
+            - DestinationAuthorized

api/wallet/spec/definitions/Webhook.yaml

@@ -0,0 +1,38 @@
+type: object
+required:
+  - identityID
+  - scope
+  - url
+properties:
+  id:
+    description: |
+      Идентификатор webhook'а
+    type: string
+    readOnly: true
+  identityID:
+    x-rebillyMerge:
+    - $ref: '#/definitions/IdentityID'
+  active:
+    description: |
+      Включена ли в данный момент доставка оповещений?
+    type: boolean
+    readOnly: true
+  scope:
+    $ref: '#/definitions/WebhookScope'
+  url:
+    description: |
+      URL, на который будут поступать оповещения о произошедших событиях
+    type: string
+    format: uri
+    maxLength: 1000
+  publicKey:
+    description: |
+      Содержимое публичного ключа, служащего для проверки авторитативности
+      приходящих на `url` оповещений
+    type: string
+    format: hexadecimal
+    readOnly: true
+    example: "\
+      MIGJAoGBAM1fmNUvezts3yglTdhXuqG7OhHxQtDFA+Ss//YuUGjw5ossDbEMoS+S\
+      IFuYZ/UL9Xg0rEHNRSbmf48OK+mz0FobEtbji8MADayzGfFopXsfRFa7MVy3Uhu5\
+      jBDpLsN3DyJapAkK0TAYINlZXxVjDwxRNheTvC+xub5WNdiwc28fAgMBAAE="

api/wallet/spec/definitions/WebhookScope.yaml

@@ -0,0 +1,14 @@
+description: |
+  Область охвата webhook'а, ограничивающая набор типов событий, по которым
+  следует отправлять оповещения
+type: object
+discriminator: topic
+required:
+  - topic
+properties:
+  topic:
+    description: Предмет оповещений
+    type: string
+    enum:
+      - WithdrawalsTopic
+      - DestinationsTopic

api/wallet/spec/definitions/WithdrawalsTopic.yaml

@@ -0,0 +1,20 @@
+description: |
+  Область охвата, включающая события по выплатам в рамках определённого кошелька
+allOf:
+  - $ref: '#/definitions/WebhookScope'
+  - type: object
+    required:
+      - eventTypes
+    properties:
+      walletID:
+        x-rebillyMerge:
+        - $ref: '#/definitions/WalletID'
+      eventTypes:
+        description: Набор типов событий выплаты, о которых следует оповещать
+        type: array
+        items:
+          type: string
+          enum:
+            - WithdrawalStarted
+            - WithdrawalSucceeded
+            - WithdrawalFailed

api/wallet/spec/paths/webhooks.yaml

@@ -0,0 +1,44 @@
+post:
+  description: Установить новый webhook.
+  tags:
+    - Webhooks
+  operationId: createWebhook
+  parameters:
+    - $ref: '#/parameters/requestID'
+    - $ref: '#/parameters/deadline'
+    - name: webhookParams
+      description: Параметры устанавливаемого webhook'а
+      in: body
+      required: true
+      schema:
+        $ref: '#/definitions/Webhook'
+  responses:
+    '201':
+      description: Webhook установлен
+      schema:
+        $ref: '#/definitions/Webhook'
+    '400':
+      $ref: '#/responses/BadRequest'
+    '401':
+      $ref: '#/responses/Unauthorized'
+
+get:
+  description: Получить набор установленных webhook'ов.
+  tags:
+    - Webhooks
+  operationId: getWebhooks
+  parameters:
+    - $ref: '#/parameters/requestID'
+    - $ref: '#/parameters/deadline'
+    - $ref: '#/parameters/queryIdentityID'
+  responses:
+    '200':
+      description: Набор webhook'ов
+      schema:
+        type: array
+        items:
+          $ref: '#/definitions/Webhook'
+    '400':
+      $ref: '#/responses/BadRequest'
+    '401':
+      $ref: '#/responses/Unauthorized'

api/wallet/spec/paths/webhooks@{webhookID}.yaml

@@ -0,0 +1,41 @@
+get:
+  description: Получить webhook по его идентификатору.
+  tags:
+    - Webhooks
+  operationId: getWebhookByID
+  parameters:
+    - $ref: '#/parameters/requestID'
+    - $ref: '#/parameters/deadline'
+    - $ref: '#/parameters/webhookID'
+    - $ref: '#/parameters/queryIdentityID'
+  responses:
+    '200':
+      description: Данные webhook'а
+      schema:
+        $ref: '#/definitions/Webhook'
+    '400':
+      $ref: '#/responses/BadRequest'
+    '401':
+      $ref: '#/responses/Unauthorized'
+    '404':
+      $ref: '#/responses/NotFound'
+
+delete:
+  description: Снять указанный webhook.
+  tags:
+    - Webhooks
+  operationId: deleteWebhookByID
+  parameters:
+    - $ref: '#/parameters/requestID'
+    - $ref: '#/parameters/deadline'
+    - $ref: '#/parameters/webhookID'
+    - $ref: '#/parameters/queryIdentityID'
+  responses:
+    '204':
+      description: Webhook успешно снят
+    '400':
+      $ref: '#/responses/BadRequest'
+    '401':
+      $ref: '#/responses/Unauthorized'
+    '404':
+      $ref: '#/responses/NotFound'

api/wallet/spec/swagger.yaml

@@ -287,6 +287,24 @@ parameters:
     maxLength: 40
     minLength: 1
 
+  webhookID:
+    name: webhookID
+    in: path
+    description: Идентификатор webhook'а
+    required: true
+    type: string
+    maxLength: 40
+    minLength: 1
+
+  queryIdentityID:
+    name: identityID
+    in: query
+    description: Идентификатор личности владельца
+    required: true
+    type: string
+    maxLength: 40
+    minLength: 1
+
 tags:
 
   - name: Providers
@@ -324,3 +342,22 @@ tags:
   - name: Downloads
     x-displayName: Загрузка файлов
     description: ""
+
+  - name: Webhooks
+    x-displayName: Webhooks
+    description: >
+      ## RBKmoney Webhooks Management API
+
+      В данном разделе описаны методы, позволяющие управлять Webhook'ами, или
+      инструментами для получения асинхронных оповещений посредством
+      HTTP-запросов при наступлении одного или группы интересующих вас событий,
+      например, о том, что выплата в рамках созданного кошелька была успешно
+      проведена.
+
+      ## RBKmoney Webhooks Events API
+
+      Внимание! Только Webhooks Management API является частью платформы
+      RBKmoney, а следовательно и данной спецификации. Для реализации
+      обработчика присылаемых уведомлений вам необходимо будет ознакомиться со
+      Swagger-спецификацей [RBKmoney Wallet Webhooks Events
+      API](https://rbkmoney.github.io/wallet-webhook-events-api/).