VK Cloud Solutions logo

Вебхуки

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

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

Примечание

Уведомления о событиях VK CS S3 предназначены для доставки хотя бы один раз. Обычно уведомления о событиях доставляются за секунды, но иногда это может занять минуту или больше.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

POST / HTTP/1.1
Host: ...
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 вы можете посмотреть здесь : https://github.com/mailru/hit-doc/tree/master/mcs-s3-webhook-server-example