Webhooks
Webhooks for VK Object Storage let you configure the sending of HTTP(S) requests based on bucket events using the API. For example, you can configure:
- processing and converting files after upload;
- integration with any external systems;
- logging for object storage.
List of events for which webhook configuration can be set up:
s3:ObjectCreated:*—PutObject,PutObjectCopy,CompleteMultipartUpload.s3:ObjectCreated:Put—PutObject.s3:ObjectCreated:Copy—PutObjectCopy.s3:ObjectCreated:CompleteMultipartUpload—CompleteMultipartUpload.s3:ObjectRemoved:*—DeleteObject.s3:ObjectRemoved:Delete—DeleteObject.
The following methods are available for working with webhooks:
PutBucketNotificationConfiguration;GetBucketNotificationConfiguration.
PUT /?notification HTTP/1.1Host: Bucket.hb.ru-msk.vkcloud-storage.ru<?xml version="1.0" encoding="UTF-8"?><NotificationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"><SimpleTopicConfiguration><Id>string</Id><Url>string</Url><Event>string</Event>...<Filter><S3Key><FilterRule><Name>string</Name><Value>string</Value></FilterRule>...</S3Key></Filter></SimpleTopicConfiguration>...</NotificationConfiguration>
This method lets you enable notifications for a specific event in the bucket (PutObject — adding an object, DeleteObject — deleting an object, etc).
Only one event type is supported: SimpleTopicConfiguration — a request to the URL provided by the user.
Example:
A request to the URL http://test.com is required when objects whose names match the image/*.png pattern are added (PutObject) to the bucketA bucket.
Request:
PUT /?notification HTTP/1.1Host: bucketA.hb.ru-msk.vkcloud-storage.ruContent-Length: 606Content-Type: application/xmlx-amz-content-sha256: 34850007f92ec3331486b48fd7db15f48315fe73c4a9b135e6d9fd629276c1e7x-amz-date: 20200831T000345ZAuthorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20200831/ru-msk/s3/aws4_request,SignedHeaders=content-md5;content-type;host;x-amz-content-sha256;x-amz-date,Signature=fc07a541c2acdbf7527eba358afa0a6d460c9bfec539dd29dfa6b5b854aae109<?xml version="1.0" encoding="UTF-8"?><NotificationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"><SimpleTopicConfiguration><Id>1</Id><Event>s3:ObjectCreated:Put</Event><Url>http://test.com</Url><Filter><S3Key><FilterRule><Name>Prefix</Name><Value>image/</Value></FilterRule><FilterRule><Name>Suffix</Name><Value>.png</Value></FilterRule></S3Key></Filter></SimpleTopicConfiguration></NotificationConfiguration>
Response:
HTTP/1.1 200 OKDate: Mon, 31 Aug 2020 17:31:43 GMTx-amz-request-id: tx00000000000000010ad2b-005a6135e2-f647d-ru-mskaContent-Length: 0Content-Type: application/xmlConnection: close
Returns the current rule configuration (SimpleNotificationConfiguration) for the bucket. If no rules have been set for this bucket, an empty NotificationConfiguration element is returned.
Request:
GET /?notification HTTP/1.1Host: my-test-bucket1.hb.ru-msk.vkcloud-storage.ruContent-Length: 0Content-Type: application/xmlx-amz-content-sha256: 34850007f92ec3331486b48fd7db15f48315fe73c4a9b135e6d9fd629276c1e7x-amz-date: 20200831T000345ZAuthorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20200831/ru-msk/s3/aws4_request,SignedHeaders=content-md5;content-type;host;x-amz-content-sha256;x-amz-date,Signature=fc07a541c2acdbf7527eba358afa0a6d460c9bfec539dd29dfa6b5b854aae109
Response:
HTTP/1.1 200Date: Mon, 31 Aug 2020 17:31:43 GMTx-amz-request-id: tx00000000000000010ad2b-005a6135e2-f647d-ru-mskaContent-Length: 1031Content-Type: application/xmlConnection: close<?xml version="1.0" encoding="UTF-8"?><NotificationConfiguration><SimpleTopicConfiguration><Id>1</Id><Event>s3:ObjectCreated:Put</Event><Url>http://test321.com</Url><Filter><S3Key><FilterRule><Name>Prefix</Name><Value>image/</Value></FilterRule><FilterRule><Name>Suffix</Name><Value>.png</Value></FilterRule></S3Key></Filter></SimpleTopicConfiguration><SimpleTopicConfiguration><Id>2</Id><Event>s3:ObjectRemoved:Delete</Event><Url>http://test123.com</Url><Filter><S3Key><FilterRule><Name>Prefix</Name><Value>image/</Value></FilterRule><FilterRule><Name>Suffix</Name><Value>.png</Value></FilterRule></S3Key></Filter></SimpleTopicConfiguration></NotificationConfiguration>
For the rules set above, when objects with names matching the image/*.png pattern are uploaded to the bucketA bucket, the following request in JSON format will be sent:
POST <URL> HTTP/1.1X-Amz-Sns-Message-Type: Notification{ "Records":[{"s3": {"object": {"eTag":"aed563ecafb4bcc5654c597a421547b2","sequencer":1577453615,"key":"some-file-to-bucket","size":100},"configurationId":"1","bucket": {"name": "bucketA","ownerIdentity": {"principalId":"mcs2883541269"}},"s3SchemaVersion":"1.0"},"eventVersion":"1.0","requestParameters":{"sourceIPAddress":"185.6.245.156"},"userIdentity": {"principalId":"2407013e-cbc1-415f-9102-16fb9bd6946b"},"eventName":"s3:ObjectCreated:Put","awsRegion":"ru-msk","eventSource":"aws:s3","responseElements": {"x-amz-request-id":"VGJR5rtJ"}}]}
When this request is executed, the VK Object Storage service validates the URL by sending the following request in XML format:
POST http://test.com HTTP/1.1X-Amz-Sns-Message-Type: Notificationcontent-type: application/json{"Timestamp":"2019-12-26T19:29:12+03:00","Type":"SubscriptionConfirmation","Message":"You have chosen to subscribe to the topic $topic. To confirm the subscription you need to response with calculated signature","TopicArn":"mcs2883541269|bucketA|s3:ObjectCreated:Put","SignatureVersion":1,"Token":"<TOKEN_VALUE>"}
To confirm the URL, you need to send a signature in response. Example:
content-type: application/json{"signature":"ea3fce4bb15c6de4fec365d36bcebbc34ccddf54616d5ca12e1972f82b6d37af"}
The signature is calculated using the formula:
signature = hmac_sha256_hex(<URL>, hmac_sha256(<TopicArn>, hmac_sha256(<Timestamp>, <Token>)))
For the example under consideration:
signature = hmac_sha256_hex(“http://test.com”, hmac_sha256(“mcs2883541269|bucketA|s3:ObjectCreated:Put”, hmac_sha256(“2019-12-26T19:29:12+03:00”, “RPE5UuG94rGgBH6kHXN9FUPugFxj1hs2aUQc99btJp3E49tA”)))
If the URL is successfully confirmed, the following response will be received in reply to the JSON request:
HTTP/1.1 200