S3 Event Notifications

1. Overview

S3 Event Notifications automatically send a message when objects in your bucket are created, removed, or affected by other supported operations. Vietnix Cloud S3 Storage implements the standard AWS S3 notification API, so code written for AWS S3 notifications can be reused as-is.

When an event occurs, the system sends an HTTP POST request with a JSON payload to the endpoint registered for the topic — typically within about a second. Kafka and AMQP destinations are also available; contact Vietnix to discuss these options.

2. How it works

Setting up notifications involves both you and Vietnix:

Task	Who does it
Prepare an endpoint that can receive JSON over HTTP/HTTPS	You
Create the notification topic on the storage cluster	Vietnix
Attach the topic to your bucket via the S3 API	You

• Topics are created by Vietnix. You cannot create a notification topic yourself through the S3 API or the portal. Request one through Vietnix support; you will receive a topic ARN in return.
• Topic ARN format: arn:aws:sns::<s3_user_id>:<topic_name>.
• Once you have the ARN, attach it to your bucket using the standard S3 API (put-bucket-notification-configuration) with any S3-compatible tool, such as AWS CLI or an SDK.

3. What you need to do

3.1. Step 1 — Prepare your endpoint

Your endpoint must:

• Be reachable over the internet — the notification service connects out to it.
• Accept POST requests with a JSON body (Content-Type: application/json).
• Return a 2xx response quickly.

Recommendations:

• Verify the sender. Allowlist the source IP 45.115.16.7 and/or check the opaqueData token that is included in every payload (see Step 2).
• Convert the payload if your destination needs it. The notification body follows the AWS S3 event message structure (see section 5). If you deliver notifications to a service that expects its own format (for example, a chat platform such as Discord, Slack, or Teams), place a small relay service in front that converts the S3 event JSON into that format.

3.2. Step 2 — Request a topic from Vietnix

Contact Vietnix support and provide:

• Bucket name
• Destination endpoint (HTTPS URL, Kafka, or AMQP)
• Event types you want to receive (see section 4)
• (Optional) a secret token used to verify notifications

Vietnix creates the topic and returns:

• TopicArn — for example arn:aws:sns::1234abcd:myevents
• Opaque token — the secret you provided; it appears in every notification in the opaqueData field.

note

• Topic names can contain letters and numbers only.
• Do not embed a secret in the query string of the endpoint URL — the notification system splits query parameters and treats them separately. Provide the secret as opaque data instead, and verify it in the payload.

3.3. Step 3 — Attach the topic to your bucket

Attach the topic ARN to your bucket with put-bucket-notification-configuration:

aws s3api put-bucket-notification-configuration \
  --bucket your-bucket-name \
  --endpoint-url https://s3.vn-hcm-1.vietnix.cloud \
  --notification-configuration '{"TopicConfigurations":[{"TopicArn":"arn:aws:sns::<s3_user_id>:<topic_name>","Events":["s3:ObjectCreated:*","s3:ObjectRemoved:*"]}]}'

3.4. Step 4 — Verify the configuration

aws s3api get-bucket-notification-configuration \
  --bucket your-bucket-name \
  --endpoint-url https://s3.vn-hcm-1.vietnix.cloud

3.5. Step 5 — Test the notification

Upload a small object to the bucket (for example with aws s3 cp) and confirm that your endpoint receives the POST request. Delivery usually takes about a second; the first notification right after changing the configuration can take a few seconds.

3.6. Step 6 — Disable notifications

Send an empty configuration:

aws s3api put-bucket-notification-configuration \
  --bucket your-bucket-name \
  --notification-configuration '{}' \
  --endpoint-url https://s3.vn-hcm-1.vietnix.cloud

4. Supported event types

Event	Triggered when
s3:ObjectCreated:*	An object is created: Put, Post, Copy, CompleteMultipartUpload
s3:ObjectRemoved:*	An object is removed: Delete, DeleteMarkerCreated
s3:ObjectLifecycle:Expiration:*	A lifecycle rule expires an object
s3:ObjectAcl:Put	An object ACL is changed
Replication events	Events related to bucket replication

5. Notification payload

{
  "Records": [{
    "eventId": "gpDqi41qbcwFMJwDPbRyDyHCs5PpX35Q",
    "opaqueData": "",
    "eventVersion": "2.1",
    "eventSource": "aws:s3",
    "eventTime": "2026-10-06T08:25:25Z",
    "awsRegion": "vn-hcm-1",
    "eventName": "ObjectCreated:Put",
    "userIdentity": { "principalId": "<s3_user_id>" },
    "requestParameters": { "sourceIPAddress": "10.64.0.252" },
    "responseElements": { "x-amz-request-id": "800000000000003100041e392832974d", "x-amz-id-2": "" },
    "s3": {
      "s3SchemaVersion": "1.0",
      "configurationId": "54661ba9-5527-4c67-af5c-d05351f472cd",
      "bucket": { "name": "your-bucket-name", "ownerIdentity": { "principalId": "<s3_user_id>" }, "arn": "arn:aws:s3:::your-bucket-name" },
      "object": { "key": "path/to/object.txt", "size": 40, "eTag": "143771125efae0940efcaf09db235578", "versionId": "null", "sequencer": "00065D27BD8F017D" }
    }
  }]
}

The opaqueData field contains the token set when the topic was created (it is empty if no token was configured).

Requests are sent with the following headers:

• User-Agent: ostor-sns-service/1.0
• Content-Type: application/json

6. Important notes and limitations

• Notifications are not signed. Verify authenticity by allowlisting the source IP 45.115.16.7 and/or checking the opaqueData value in the payload.
• Your webhook must return a 2xx response quickly. If the endpoint returns an error (for example, a 500), the event is not retried and is lost. Events that have not been delivered yet are also lost if the notification service restarts. If your workflow cannot tolerate lost events, reconcile periodically with ListObjects.
• sourceIPAddress in the payload is the internal gateway IP, not the original client IP.
• awsRegion is vn-hcm-1 (the region of the S3 cluster).
• Deleting an object that does not exist does not generate an event.
• A slow or dead webhook does not slow down uploads. In testing, an endpoint hanging for 30 seconds did not affect upload time (still ~0.4 s).
• The first notification after changing the configuration can take a few seconds; subsequent requests are delivered normally.

7. Best practices

• Verify every notification with the opaqueData token before processing.
• Return 2xx immediately and process the event asynchronously to avoid delivery timeouts.
• Design for possible event loss: if events are business-critical, run a periodic reconciliation (for example, ListObjects) to detect objects whose events were missed.
• Restrict your webhook to the Vietnix source IP 45.115.16.7.
• Test with a staging bucket before enabling notifications on production data.

8. What's Next?

• Manage Bucket: Learn how to manage S3 buckets in Vietnix Cloud.
• Object Lock: Protect objects with WORM retention.
• AWS CLI: Connect AWS CLI to Vietnix Cloud S3 Storage.