valitydev/swag-wallets-webhook-events
14
0
Fork 0
mirror of https://github.com/valitydev/swag-wallets-webhook-events.git synced 2024-11-06 10:05:19 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

deploy: a8289160bd

Browse Source
This commit is contained in:
tolkonepiu 2023-08-08 13:00:18 +00:00
parent 9b18429cb5
commit 04f4a733ea
2 changed files with 154 additions and 207 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

92
openapi.json
View File

File diff suppressed because one or more lines are too long

269
openapi.yaml
View File

@ -10,144 +10,97 @@ info:
## Wallet Webhook Events API
Данная спецификация определяет протокол доставки оповещений о возникновении
новых событий по кошелькам в рамках вашей организации, которые система
доставляет в
виде HTTP-запросов на URL-адреса созданных вами webhook'ов. Обработчики для
подобного рода запросов необходимо реализовать на стороне вашего серверного
кода согласно данной спецификации.
The specification defines a protocol for delivering notifications about new
wallet events within your organisation. The notifications are deliveried by
the system as HTTP requests to the URL of webhooks you created. Handlers for
such kind of queries should be implemented on the side of your server code
according to the specification.
Webhook — это подписка на определенный тип события либо их группу,
касающихся различных объектов в рамках вашей организации. Для управления
webhook'ами используются методы API, описанные в спецификации
[Vality Webhook Management API](https://github.com/valitydev/swag-wallets).
Когда наступает одно из событий в рамках определенного кошелька (например,
изменение статуса кошелька), система выбирает
webhook, подходящий под этот тип события, и отправляет HTTP-запрос,
содержащий сообщение в формате JSON на указанный в этом webhook'е URL. Если
вы создали несколько webhook'ов, подходящих под этот тип события, то событие
доставляется одновременно на все заданные в них URL в неопределённом
порядке.
Webhook is a subscription to a specific type of event or group of events
relating to different objects within your organisation. API methods
described in the specification [Vality Webhook Management
API](https:/github.com/valitydev/swag-wallets) are used to manage webhooks.
## Стратегия доставки
When within the wallet one of the events occurs (e.g. a wallet status
change), the system selects a webhook matching that event type and sends an
HTTP request containing a JSON message to the URL specified in the webhook.
If several webhooks matching this event type were created, the event is
simultaneously delivered to all URLs specified in those webhooks in an
undefined order.
## Delivery strategy
The system guarantees events delivery order within a specific notification
subject (wallet, deposit, withdrawal, etc.). The system maintains a message
queue for each notification item to keep the sequence and ensure the
guaranteed delivery.
Система гарантирует порядок доставки событий в рамках определенного предмета
оповещения
A delivery request is considered to be successful only when a response with
status `200` is received. The system will wait for a successful response to
the sent a request during 10 seconds. In case of a response with any other
status or after expiration of the specified time which was reserved to
process the notification, the system will try to re-deliver notifications
until a successful response is received, or until a decision is made that it
is impossible to deliver information. Delivery attempts will be made at the
following time intervals between requests:
(кошелек, пополнение, выплата и т.п.). Система поддерживает очередь
сообщений для каждого
- 30 seconds,
- 5 minutes,
- 15 minutes,
- 1 hour.
- every hour within 24 hours
предмета оповещения, чтобы соблюсти очередность и гарантированную доставку.
If the last attempt of notification delivery fails, all the events that have
been accumulated in this wallet queue are discarded.
## Received messages authorization
The system confirms notifications authenticity by signing messages with a
private key that is unique to each webhook, the paired public key of which
is contained in the data of that webhook. The signature is transmitted in
the HTTP header Content-Signature. Represented in various atributes the
header contains the information about the algorithm used to create a
signature and content of the signature in the format [URL-safe
base-64](https://tools.ietf.org/html/rfc4648).
Запрос на доставку считается успешным только при получении ответа со
статусом `200`. Система будет ожидать успешного ответа на отправленный
запрос в течение 10 секунд. В случае ответа любым другим статусом или по
истечении указанного времени, отведённого на обработку оповещения, система
будет пытаться повторно доставить оповещения до получения успешного ответа,
либо до принятия решения о невозможности доставить информацию. Попытки
доставки будут производиться со следующими временными интервалами между
запросами:
- 30 секунд,
- 5 минут,
- 15 минут,
- 1 час.
- каждый час в течение суток (24 часа)
Если последняя попытка доставить оповещение оканчивается неудачей, все
события, которые
накопились в очереди этого кошелька, отбрасываются.
``` Content-Signature: alg=RS256;
digest=zFuf7bRH4RHwyktaqHQwmX5rn3LfSb4dKo... ```
## Авторизация полученных сообщений
Система подтверждает подлинность оповещений, подписывая сообщения
приватным ключом, уникальным для каждого webhook'а, парный публичный ключ к
которому содержится в данных этого webhook'а. Подпись передается в
HTTP-заголовке `Content-Signature`. В заголовке в виде различных атрибутов
содержится информация об использованном при формировании подписи алгоритме и
значение подписи в формате
[URL-safe base-64](https://tools.ietf.org/html/rfc4648).
```
Content-Signature: alg=RS256; digest=zFuf7bRH4RHwyktaqHQwmX5rn3LfSb4dKo...
```
На данный момент возможно использование единственного алоритма формирования
подписи.
At the moment the only one signature generation algorithm is possible to
use.
### [RS256](https://tools.ietf.org/html/rfc7518#section-3.3)
Подпись формируется согласно алгоритму
[RSASSA-PKCS1-v1_5](https://tools.ietf.org/html/rfc3447#section-8.2), на
вход которому подаётся результат вычисления хэша сообщения по алгоритму
[SHA-256](https://tools.ietf.org/html/rfc6234).
The signature is generated according to
[RSASSA-PKCS1-v1_5](https://tools.ietf.org/html/rfc3447#section-8.2)
algorithm , which itself uses result of message
[SHA-256](https://tools.ietf.org/html/rfc6234) calculation.
Набор атрибутов заголовка и список возможных алгоритмов формирования подписи
в дальнейшем могут быть расширены.
The set of header attributes and the list of possible signature generation
algorithms can be expanded later.
servers:
- url: https://merchant.site
tags:
- name: Event Notifications
x-displayName: Оповещения
description: Доставка оповещений о событиях системы.
x-displayName: Notifications
description: Delivery of platform event notifications.
paths:
/webhook:
post:
tags:
- Event Notifications
summary: Оповестить о событии
summary: Notify of an event
operationId: notifyWebhookEvent
parameters:
- $ref: '#/components/parameters/signature'
requestBody:
description: Данные произошедшего в платформе события
description: Data from an event that occurred in the platform
required: true
content:
application/json:
@ -155,20 +108,20 @@ paths:
$ref: '#/components/schemas/Event'
responses:
'200':
description: Оповещение обработано
description: Notification processed
components:
parameters:
signature:
name: Content-Signature
in: header
description: |
Подпись сообщения, сформированная согласно указанным выше правилам
Message signature formed according to the above rules
required: true
schema:
type: string
schemas:
Event:
description: Данные события
description: Event data
type: object
required:
- occuredAt
@ -176,21 +129,21 @@ components:
- eventType
properties:
eventID:
description: Идентификатор события в системе
description: Event identifier
type: string
occuredAt:
description: Дата и время возникновения события
description: Date and time the event occurrence
type: string
format: date-time
topic:
description: Предмет оповещения
description: Subject of notification
type: string
enum:
- WithdrawalTopic
- DestinationTopic
eventType:
type: string
description: Тип произошедшего с предметом оповещения события
description: Type of event that occurred
enum:
- WithdrawalStarted
- WithdrawalSucceeded
@ -208,23 +161,23 @@ components:
DestinationAuthorized: '#/components/schemas/DestinationAuthorized'
DestinationUnauthorized: '#/components/schemas/DestinationUnauthorized'
WithdrawalID:
description: Идентификатор вывода денежных средств
description: Identifier of funds withdrawal
type: string
example: tZ0jUmlsV0
DestinationID:
description: Идентификатор места назначения денежных средств
description: Destination identifier
type: string
example: 10ASF74D98
CurrencyID:
description: |
Валюта, символьный код согласно [ISO
description: >
Currency, character code according to [ISO
4217](http://www.iso.org/iso/home/standards/currency_codes.htm).
type: string
pattern: ^[A-Z]{3}$
example: RUB
WithdrawalBody:
description: |
Объём средств, которые необходимо вывести
Amount of funds to be withdrawn
type: object
required:
- amount
@ -232,27 +185,27 @@ components:
properties:
amount:
description: |
Сумма денежных средств в минорных единицах, например, в копейках
The amount of money in minor units, for example, in cents
type: integer
format: int64
example: 1430000
currency:
$ref: '#/components/schemas/CurrencyID'
WalletID:
description: Идентификатор кошелька
description: Identifier of the wallet
type: string
example: '10068321'
ExternalID:
description: >
Уникальный идентификатор сущности на вашей стороне.
The unique identifier of the content on your side.
При указании будет использован для того, чтобы гарантировать
идемпотентную обработку операции.
When specified, will be used to ensure idempotent processing of the
operation.
type: string
example: '10036274'
Withdrawal:
description: Данные вывода денежных средств
description: Funds withdrawal data
type: object
required:
- wallet
@ -262,7 +215,7 @@ components:
id:
$ref: '#/components/schemas/WithdrawalID'
createdAt:
description: Дата и время запуска вывода
description: Date and time the withdrawal started
type: string
format: date-time
destination:
@ -271,16 +224,14 @@ components:
$ref: '#/components/schemas/WithdrawalBody'
metadata:
description: >
Произвольный, специфичный для клиента API и непрозрачный для системы
набор данных, ассоциированных с
данным выводом
A custom client-specific API and a data set that is not transparent
to the system, associated with this withdrawal
wallet:
$ref: '#/components/schemas/WalletID'
externalID:
$ref: '#/components/schemas/ExternalID'
WithdrawalStarted:
description: Событие о начале осуществления вывода средств
description: Withdrawal start event
allOf:
- $ref: '#/components/schemas/Event'
- type: object
@ -290,7 +241,7 @@ components:
withdrawal:
$ref: '#/components/schemas/Withdrawal'
WithdrawalSucceeded:
description: Событие об успешном осуществлении вывода средств
description: Successful withdrawal event
allOf:
- $ref: '#/components/schemas/Event'
- type: object
@ -302,7 +253,7 @@ components:
externalID:
$ref: '#/components/schemas/ExternalID'
WithdrawalFailed:
description: Событие о неуспешном осуществлении вывода средств
description: Unsuccessful withdrawal event
allOf:
- $ref: '#/components/schemas/Event'
- type: object
@ -314,20 +265,18 @@ components:
externalID:
$ref: '#/components/schemas/ExternalID'
IdentityID:
description: Идентификатор личности владельца кошелька
description: Identifier of wallet owner
type: string
example: tZ0jUmlsV0
DestinationResource:
description: >-
Ресурс приёмника денежных средств, используемый для осуществления
выводов
description: Asset receiver resource used to make withdrawals
type: object
required:
- type
properties:
type:
description: |
Тип ресурса приёмника средств.
Destination resource type
type: string
enum:
- BankCard
@ -340,17 +289,17 @@ components:
CryptoWallet: '#/components/schemas/CryptoWallet'
DigitalWallet: '#/components/schemas/DigitalWallet'
BankCardPaymentSystem:
description: Платежная система
description: Payment system
type: string
BankCardTokenProvider:
description: Провайдер платежных токенов
description: Payment token provider
type: string
enum:
- applepay
- googlepay
- samsungpay
BankCard:
description: Данные банковской карты
description: Bank card details
allOf:
- $ref: '#/components/schemas/DestinationResource'
- type: object
@ -359,15 +308,15 @@ components:
- paymentSystem
properties:
cardNumberMask:
description: Маскированый номер карты
description: Masked card number
type: string
pattern: ^\d{6,8}\*+\d{2,4}$
bin:
description: BIN банка-эмитента карты
description: Card issuing bank BIN
type: string
pattern: ^\d{6,8}$
lastDigits:
description: Последние цифры номера карты
description: Card last digits
type: string
pattern: ^\d{2,4}$
paymentSystem:
@ -375,7 +324,7 @@ components:
tokenProvider:
$ref: '#/components/schemas/BankCardTokenProvider'
CryptoCurrency:
description: Криптовалюта
description: Cryptocurrency
type: string
enum:
- Bitcoin
@ -385,7 +334,7 @@ components:
- Ethereum
- Zcash
CryptoWallet:
description: Данные криптовалютного кошелька
description: Cryptocurrency wallet details
allOf:
- $ref: '#/components/schemas/DestinationResource'
- type: object
@ -394,7 +343,7 @@ components:
- currency
properties:
cryptoWalletId:
description: Идентификатор (он же адрес) криптовалютного кошелька
description: Identifier (aka address) of a cryptocurrency wallet
type: string
minLength: 16
maxLength: 256
@ -402,7 +351,7 @@ components:
currency:
$ref: '#/components/schemas/CryptoCurrency'
DigitalWallet:
description: Данные криптовалютного кошелька
description: Cryptocurrency wallet details
allOf:
- $ref: '#/components/schemas/DestinationResource'
- type: object
@ -411,17 +360,17 @@ components:
- digitalWalletProvider
properties:
digitalWalletId:
description: Идентификатор кошелька
description: E-wallet identifier
type: string
minLength: 16
maxLength: 256
example: zu3TcwGI71Bpaaw2XkLWZXlhMdn4zpVzMQ
digitalWalletProvider:
description: Провайдер электронных денежных средств
description: Electronic assets service provider
type: string
example: Paypal
Destination:
description: Данные приемника денежных средств
description: Destination data
type: object
required:
- name
@ -433,8 +382,8 @@ components:
$ref: '#/components/schemas/DestinationID'
name:
description: >
Человекочитаемое название приёмника средств, по которому его легко
узнать
A human-readable name for the receiver by which it is easily
recognizable
type: string
example: Squarey plastic thingy
identity:
@ -445,17 +394,15 @@ components:
$ref: '#/components/schemas/DestinationResource'
metadata:
description: >
Произвольный, специфичный для клиента API и непрозрачный для системы
набор данных, ассоциированных с
данным приёмником
An arbitrary, client-specific API and non-transparent set of data
associated with given receiver
type: object
example:
color_hint: olive-green
externalID:
$ref: '#/components/schemas/ExternalID'
DestinationCreated:
description: Событие создания приемника денежных средств
description: Destination creation event
allOf:
- $ref: '#/components/schemas/Event'
- type: object
@ -465,7 +412,7 @@ components:
destination:
$ref: '#/components/schemas/Destination'
DestinationAuthorized:
description: Смена статуса приемника на авторизованный
description: Changing the status of the destination receiver to authorized
allOf:
- $ref: '#/components/schemas/Event'
- type: object
@ -477,7 +424,7 @@ components:
externalID:
$ref: '#/components/schemas/ExternalID'
DestinationUnauthorized:
description: Смена статуса приемника на не авторизованный
description: Changing the status of the destination receiver to unauthorized
allOf:
- $ref: '#/components/schemas/Event'
- type: object