Вебхуки

Обновлена 15 апреля 2024 г. в 08:50

Вебхуки

Функция вебхуков Cloud Storage позволяет получать уведомления, когда в бакете происходят определенные события. Чтобы включить уведомления, необходимо сначала добавить конфигурацию уведомлений. Она содержит события, по которым нужно отсылать запросы на клиентский сервис, и сам адрес клиентского сервиса. Эта конфигурация сохраняется в меню Webhooks, которое привязано к бакету.

В настоящее время Cloud Storage может публиковать уведомления о следующих событиях:

События создания новых объектов Cloud Storage поддерживает несколько API для создания объектов. Можно запросить уведомление, когда используется только конкретный API (например, s3:ObjectCreated), или можно использовать подстановочный знак (например, s3:ObjectCreated:*) для запроса уведомления при создании объекта независимо от используемого API.
События удаления объектов — поддержка удаление объектов. Можно запросить уведомление, когда объект удален, используя s3:ObjectRemoved тип события. Также можно использовать подстановочный знак s3:ObjectRemoved:* для запроса уведомления при каждом удалении объекта.

Включение уведомлений — это операция на уровне бакета. Она сохраняет информацию о конфигурации уведомлений. Они представляют собой:

префикс и/или суффикс файлов, для которых будут отправляться события;
метод запроса Cloud Storage;
url, по которому отправляется событие.

Включить уведомления вы можете как с панели управления VK Cloud, так и используя апи. Например с помощью cli.

Интерфейс панели VK CS позволяет настроить конфигурацию уведомлений для бакета без написания кода. Для создания уведомления следует воспользоваться кнопкой «Добавить» во вкладке «Wehooks» выбранного бакета.

В появившемся окне следует ввести требуемые параметры и подтвердить кнопкой «Добавить hook».

На внутреннем уровне и панель VK Cloud, и SDK вызывают Cloud Storage REST API для управления подресурсами уведомлений, связанных с бакетом.

Независимо от того, какой метод используется, Cloud Storage сохраняет конфигурацию уведомлений в виде XML на подресурсах уведомлений, связанных с бакетом.

По умолчанию уведомления не включены ни для каких событий. Таким образом, изначально подресурс уведомления хранит пустую конфигурацию.

<NotificationConfiguration xmlns="http://<имя_бакета>.hb.vkcs.cloud/image/01.jpg/"> </NotificationConfiguration>

Чтобы включить уведомления для событий определенных типов, следует заменить XML на соответствующую конфигурацию, которая определяет типы событий, которые должен публиковать Cloud Storage, и место назначения, в котором необходимо публиковать события.

Для включения уведомлений нужно понимать, что Hotbox верифицирует то, что адрес, на который будут уходить события, действительно ваш. Это происходит следующим образом:

Вы отправляете запрос на создание определенной конфигурации webhook в hotbox.
Hotbox отправит по указанному в конфигурации адресу запрос для верификации с указанием времени, временного токена и тд. И будет ждать от вашего сервиса в ответ посчитанную сигнатуру на основе переданных параметров. Если сигнатура верная, то ваша конфигурация webhook будет сохранена.

Как выглядит этот запрос:

POST / HTTP/1.1Host: ...X-Amz-Sns-Message-Type: SubscriptionConfirmation{"Timestamp":"2021-04-22T16:48:37+03:00","Type":"SubscriptionConfirmation","Message":"You have chosen to subscribe to the topic $topic\\nTo confirm the subscription you need to response with calculated signature","TopicArn":"mcs00000000|test|s3:ObjectCreated:Put","SignatureVersion":1,"Token":"9fbYYWYGANVGeQ3s9VKxrYgynwqu65PwQ6zr7bVvU4WKXf2W"}

Ваш сервис должен ответить посчитанной сигнатурой:

{"signature":"98f5f6db741e0e292809bf95ea6c0302fe98b68530e5281bc741269f06270f49"}

Как эта сигнатура считается:

signature = HMAC-SHA256-HEX(Url, HMAC-SHA256(TopicArn, HMAC-SHA256(Time, Token)))

Пример клиентского сервиса на golang вы можете посмотреть здесь.