Bucket Notifications

MinIO AIStor bucket notifications allow administrators to send notifications to supported external services when events occur on objects or buckets, similar to Amazon S3 Event Notifications. This page lists supported event types that trigger notifications, including bucket-level and object-level S3 events.

MinIO AIStor supports publishing event notifications to the following targets:

MinIO AIStor supports either asynchronous (default) or synchronous bucket notifications for all remote targets.

With asynchronous delivery, MinIO AIStor sends the event to the configured remote and does not wait for a response before continuing to the next event. Asynchronous bucket notification prioritizes sending events with the risk of some events being lost if the remote target has a transient issue during transit or processing.

With synchronous delivery, MinIO AIStor sends the event to the configured remote and then waits for the remote to confirm a successful receipt before continuing to the next event. Synchronous bucket notification prioritizes delivery of events with the risk of a slower event-send rate and queue fill.

To enable synchronous bucket notifications for all configured remote targets, use either of the following settings:

• Set the MINIO_API_SYNC_EVENTS environment variable to on and restart the Object Store.
• Set the api.sync_events configuration setting to on and restart the Object Store.

For synchronous and asynchronous events, MinIO AIStor maintains a per-remote queue where it stores unsent and pending events. The queue limit defaults to 100000.

MinIO AIStor discards new events when the queue is full.

You can increase the queue size as necessary to better accommodate the rate of event send and processing of the MinIO AIStor deployment and remote target. Use the QUEUE_LIMIT environment variable or configuration setting for your notification method to modify this limit.

For asynchronous events, MinIO AIStor allows a maximum of 50000 concurrent send calls.

MinIO AIStor bucket notifications are compatible with Amazon S3 Event Notifications. This section lists all supported events.

MinIO AIStor supports triggering notifications on the following S3 object events:

• s3:ObjectAccessed:Get
• s3:ObjectAccessed:GetLegalHold
• s3:ObjectAccessed:GetRetention
• s3:ObjectAccessed:Head

s3:ObjectAccessed:\* selects all s3:ObjectAccessed-prefixed events.

• s3:ObjectCreated:CompleteMultipartUpload
• s3:ObjectCreated:Copy
• s3:ObjectCreated:DeleteTagging
• s3:ObjectCreated:Post
• s3:ObjectCreated:Put
• s3:ObjectCreated:PutLegalHold
• s3:ObjectCreated:PutRetention
• s3:ObjectCreated:PutTagging

s3:ObjectCreated:\* selects all s3:ObjectCreated-prefixed events.

• s3:ObjectRemoved:Delete
• s3:ObjectRemoved:DeleteMarkerCreated

s3:ObjectRemoved:\* selects all s3:ObjectRemoved-prefixed events.

MinIO AIStor supports triggering notifications on the originating server for replication events. To avoid duplicate replication event notifications, MinIO AIStor does not trigger notifications on the destination cluster by default.

If you need notifications on the destination cluster as well, contact MinIO Engineering through SUBNET.

MinIO AIStor supports notification for the following S3 replication events for either bucket replication or site replication:

• s3:Replication:OperationCompletedReplication
• s3:Replication:OperationFailedReplication
• s3:Replication:OperationMissedThreshold
• s3:Replication:OperationNotTracked
• s3:Replication:OperationReplicatedAfterThreshold

s3:Replication:\* selects all s3:Replication-prefixed events.

MinIO AIStor supports S3 Replication Time Control (RTC) events for monitoring replication SLA compliance. These events track whether objects replicate within a configured time threshold. MinIO AIStor measures replication time from when an object is written to the source bucket until it successfully replicates to all configured remote targets.

Configure the replication threshold with the MINIO_REPLICATION_EVENT_THRESHOLD environment variable.

• s3:ObjectReplicationMissedThreshold
• s3:ObjectReplicationReplicatedAfterThreshold

Replication Time Control (RTC) threshold events require MinIO AIStor RELEASE.2026-02-02T23-40-11Z or later.

MinIO AIStor supports triggering notifications on the following S3 ILM transition events:

• s3:ObjectRestore:Post
• s3:ObjectRestore:Completed

s3:ObjectRestore:\* selects all s3:ObjectRestore-prefixed events.

• s3:ObjectTransition:Failed
• s3:ObjectTransition:Complete

s3:ObjectTransition:\* selects all s3:ObjectTransition-prefixed events.

MinIO AIStor supports triggering notifications on the following S3 scanner events:

• s3:Scanner:ManyVersions

  Emitted when an object has a version count at or above the configured threshold. Defaults to objects with 100 or more versions. Configure the threshold with MINIO_SCANNER_ALERT_EXCESS_VERSIONS.

• s3:Scanner:LargeVersions

  Emitted when the total storage size of all versions for a single object reaches or exceeds 1 TiB. This threshold is fixed and not configurable.

• s3:Scanner:BigPrefix

  Emitted when a prefix has a subfolder count above the configured threshold. Defaults to prefixes with more than 50,000 subfolders. Configure the threshold with MINIO_SCANNER_ALERT_EXCESS_FOLDERS.

s3:Scanner:\* selects all s3:Scanner-prefixed events.

MinIO AIStor supports triggering notifications on the following global events. You can only listen to these events through the ListenNotification API:

• s3:BucketCreated
• s3:BucketRemoved

All notification payloads use the same overall schema. Depending on the type of notification, some fields may be omitted or have null values.

{
  "eventVersion": "string",
  "eventSource": "string",
  "awsRegion": "string",
  "eventTime": "string",
  "eventName": "string",
  "userIdentity": {
    "principalId": "string"
  },
  "requestParameters": {
    "key": "value"
  },
  "responseElements": {
    "key": "value"
  },
  "s3": {
    "s3SchemaVersion": "string",
    "configurationId": "string",
    "bucket": {
      "name": "string",
      "ownerIdentity": {
        "principalId": "string"
      },
      "arn": "string"
    },
    "object": {
      "key": "string",
      "size": 10000,
      "eTag": "string",
      "contentType": "string",
      "userMetadata": {
        "key": "string"
      },
      "versionId": "string",
      "sequencer": "string"
    }
  },
  "source": {
    "host": "string",
    "port": "string",
    "userAgent": "string"
  }
}

The following example is a notification for an s3:ObjectCreated:Put event:

{
  "EventName": "s3:ObjectCreated:Put",
  "Key": "test-bucket/image.jpg",
  "Records": [
    {
      "eventVersion": "2.0",
      "eventSource": "minio:s3",
      "awsRegion": "",
      "eventTime": "2025-02-06T01:04:31.998Z",
      "eventName": "s3:ObjectCreated:Put",
      "userIdentity": {
        "principalId": "access_key"
      },
      "requestParameters": {
        "principalId": "access_key",
        "region": "",
        "sourceIPAddress": "192.168.1.10"
      },
      "responseElements": {
        "x-amz-id-2": "dd9025bab4ad464b049177c95eb6ebf374d3b3fd1af9251148b658df7ac2e3e8",
        "x-amz-request-id": "182178E8B36AC9DF",
        "x-minio-deployment-id": "2369dcb4-348b-4d30-8fc9-61ab089ba4bc",
        "x-minio-origin-endpoint": "https://aistor.test.svc.cluster.local"
      },
      "s3": {
        "s3SchemaVersion": "1.0",
        "configurationId": "Config",
        "bucket": {
          "name": "test-bucket",
          "ownerIdentity": {
            "principalId": "access_key"
          },
          "arn": "arn:aws:s3:::test-bucket"
        },
        "object": {
          "key": "image.jpg",
          "size": 84452,
          "eTag": "eb52f8e46f60a27a8a1a704e25757f30",
          "contentType": "image/jpeg",
          "userMetadata": {
            "content-type": "image/jpeg"
          },
          "sequencer": "182178E8B3728CAC"
        }
      },
      "source": {
        "host": "192.168.1.10",
        "port": "",
        "userAgent": "MinIO (linux; amd64) minio-go/v7.0.83"
      }
    }
  ]
}