VK Cloud logo
Обновлена1 августа 2023 г. в 07:04

Вебхуки

Общая информация

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

Список уведомлений

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

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

Включение уведомления

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

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

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

Использование панели управления VK Cloud

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

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

Программное использование AWS SDK

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

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

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

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

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

Верификация указанного в конфигурации url

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

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

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

1POST / HTTP/1.1
2Host: ...
3X-Amz-Sns-Message-Type: SubscriptionConfirmation
4
5{"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 вы можете посмотреть здесь.