HOOK-1: Describe webhook resources (#55)

* HOOK-1: Describe webhook resources

* HOOK-1: Deprecate and remove callback handlers

* HOOK-1: Get rid of allOfs hacked earlier to inject descriptions

spec/definitions/BrowserPostRequest.yaml

@@ -14,6 +14,4 @@ allOf:
           [RFC6570](https://tools.ietf.org/html/rfc6570).
         type: string
       form:
-        description: Форма для отправки средствами браузера
-        allOf:
-          - $ref: '#/definitions/UserInteractionForm'
+        $ref: '#/definitions/UserInteractionForm'

spec/definitions/CallbackHandler.yaml

@@ -1,9 +0,0 @@
-type: object
-required:
-  - url
-  - publicKey
-properties:
-  url:
-    type: string
-  publicKey:
-    type: string

spec/definitions/ClientInfo.yaml

@@ -1,3 +1,4 @@
+description: Данные клиентского устройства плательщика
 type: object
 required:
   - fingerprint

spec/definitions/ContactInfo.yaml

@@ -1,3 +1,4 @@
+description: Контактные данные плательщика
 type: object
 properties:
   email:

spec/definitions/InvoicesTopic.yaml

@@ -0,0 +1,29 @@
+description: |
+  Область охвата, включающая события по инвойсам в рамках определённого
+  магазина
+allOf:
+  - $ref: '#/definitions/WebhookScope'
+  - type: object
+    required:
+      - shopID
+      - eventTypes
+    properties:
+      shopID:
+        description: Идентификатор магазина
+        type: integer
+        format: int32
+      eventTypes:
+        description: Набор типов событий инвойсов, о которых следует оповещать
+        type: array
+        items:
+          type: string
+          enum:
+            - InvoiceCreated
+            - InvoicePaid
+            - InvoiceCancelled
+            - InvoiceFulfilled
+            - PaymentStarted
+            - PaymentProcessed
+            - PaymentCaptured
+            - PaymentCancelled
+            - PaymentFailed

spec/definitions/LogicError.yaml

@@ -1,3 +1,4 @@
+description: Описание ошибки, возникшей в процессе проведения платежа
 type: object
 required:
   - code

spec/definitions/Payment.yaml

@@ -29,9 +29,7 @@ allOf:
         description: Идентификатор платежной сессии
         type: string
       contactInfo:
-        description: Контактные данные плательщика
-        allOf:
-          - $ref: '#/definitions/ContactInfo'
+        $ref: '#/definitions/ContactInfo'
       amount:
         description: >
           Стоимость предлагаемых товаров или услуг, в минорных денежных

spec/definitions/PaymentParams.yaml

@@ -11,6 +11,4 @@ properties:
     description: Идентификатор платежной сессии
     type: string
   contactInfo:
-    description: Контактные данные плательщика
-    allOf:
-      - $ref: '#/definitions/ContactInfo'
+    $ref: '#/definitions/ContactInfo'

spec/definitions/PaymentStatus.yaml

@@ -12,6 +12,4 @@ properties:
       - cancelled
       - failed
   error:
-    description: Описание ошибки, возникшей в процессе проведения платежа
-    allOf:
-      - $ref: '#/definitions/LogicError'
+    $ref: '#/definitions/LogicError'

spec/definitions/PaymentToolTokenParams.yaml

@@ -6,6 +6,4 @@ properties:
   paymentTool:
     $ref: '#/definitions/PaymentTool'
   clientInfo:
-    description: Данные клиентского устройства плательщика
-    allOf:
-      - $ref: '#/definitions/ClientInfo'
+    $ref: '#/definitions/ClientInfo'

spec/definitions/Shop.yaml

@@ -27,5 +27,3 @@ properties:
     format: int32
   account:
     $ref: '#/definitions/ShopAccount'
-  callbackHandler:
-    $ref: '#/definitions/CallbackHandler'

spec/definitions/ShopParams.yaml

@@ -15,5 +15,3 @@ properties:
   payoutToolID:
     type: integer
     format: int32
-  callbackUrl:
-    type: string

spec/definitions/UpdateShopParams.yaml

@@ -11,5 +11,3 @@ properties:
   payoutToolID:
     type: integer
     format: int32
-  callbackUrl:
-    type: string

spec/definitions/UserInteractionForm.yaml

@@ -1,3 +1,4 @@
+description: Форма для отправки средствами браузера
 type: array
 items:
   type: object

spec/definitions/Webhook.yaml

@@ -0,0 +1,29 @@
+type: object
+required:
+  - id
+  - active
+  - scope
+  - url
+  - publicKey
+properties:
+  id:
+    description: |
+      Идентификатор webhook'а
+    type: string
+  active:
+    description: |
+      Включена ли в данный момент доставка оповещений?
+    type: boolean
+  scope:
+    $ref: '#/definitions/WebhookScope'
+  url:
+    description: |
+      URL, на который будут поступать оповещения о произошедших событиях
+    type: string
+    format: url
+  publicKey:
+    description: |
+      Содержимое публичного ключа, служащего для проверки авторитативности
+      приходящих на `url` оповещений
+    type: string
+    format: hexadecimal

spec/definitions/WebhookParams.yaml

@@ -0,0 +1,13 @@
+description: Данные для установки нового webhook'а
+type: object
+required:
+  - scope
+  - url
+properties:
+  scope:
+    $ref: '#/definitions/WebhookScope'
+  url:
+    description: |
+      URL, на который будут поступать оповещения о произошедших событиях
+    type: string
+    format: url

spec/definitions/WebhookScope.yaml

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

spec/paths/processing@webhooks.yaml

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

spec/paths/processing@webhooks@{webhookID}.yaml

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

spec/swagger.yaml

@@ -117,6 +117,12 @@ parameters:
     required: true
     type: integer
     format: int32
+  webhookID:
+    name: webhookID
+    in: path
+    description: Идентификатор webhook'а
+    required: true
+    type: string
   fromTime:
     name: fromTime
     in: query
@@ -210,14 +216,16 @@ tags:
 
       # Асинхронные уведомления
 
-      В каждом магазине возможно указать URL для получения асинхронных
-      уведомлений (callback) об изменении состояния данных. Например, если вы
-      используете неперсистентные интерпретируемые языки разработки, такие как
-      PHP, вы можете указать callback URL вашего приложения, на который
-      платформа будет отправлять данных об изменении состояния инвойса. Для
-      проверки подлинности присланных на ваш callback URL данных используется
-      ключ для обратных нотификаций (Callback Key), который является публичным
-      ключом платформы. Получить данный ключ можно в вашем личном кабинете.
+      Для любого магазина можно указать URL для получения асинхронных оповещений
+      об изменении состояния данных при помощи установки webhook'а. Например,
+      если вы используете неперсистентные интерпретируемые языки разработки,
+      такие как PHP, вы можете установить webhook, указав URL вашего приложения,
+      на который платформа будет отправлять данных об изменении состояния
+      инвойса. Для проверки подлинности присланных на URL вашего приложения
+      данных используется соответствующий публичный ключ, который создаётся при
+      установке этого webhook'а и получить который можно в вашем личном
+      кабинете.
+
   - name: Invoices
     x-displayName: Инвойсы
     description: >
@@ -252,8 +260,8 @@ tags:
       Платформа предоставляет вам возможность заполнить и сохранить любые
       необходимые метаданные в структуре инвойса. Данные описываются массивом
       JSON. В дальнейшем платформа предоставит вам эти данные при запросе данных
-      инвойса по его ID либо пришлет в асинхронном режиме на указанный Callback
-      URL.
+      инвойса по его ID либо пришлет в асинхронном режиме на webhook,
+      установленный для соответствующего магазине, если он есть.
 
       # События инвойса
 
@@ -296,8 +304,8 @@ tags:
       предоставляет вам интерфейс, позволяющий со стороны вашего серверного кода
       инициировать и контролировать процесс списания денег. Данный процесс может
       быть, как синхронным, когда вы ожидаете ответа системы, так и асинхронным,
-      когда после запуска платежа вы ожидаете уведомлений на callback URL
-      магазина.
+      когда после запуска платежа вы ожидаете уведомлений на установленный для
+      соответствующего магазина webhook.
 
       # Платежная сессия
 
@@ -359,6 +367,8 @@ tags:
 
       Любые изменения данных требуют верификации на стороне платформы путем
       создания заявок на изменение.
+  - name: Webhooks
+    x-displayName: Webhooks
   - name: Geo
     x-displayName: Геопозиционирование
     description: >