Bucket notifications

MinIO bucket notifications allow administrators to send notifications to supported external services on certain object or bucket events. MinIO supports bucket and object-level S3 events similar to the Amazon S3 Event Notifications.

Supported notification targets

MinIO supports publishing event notifications to the following targets:

Asynchronous vs synchronous bucket notifications

With asynchronous delivery, MinIO fires the event at 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 fires the event at 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 MinIO deployment.
• Set the api.sync_events configuration setting to on and restart the MinIO deployment.

Supported S3 event types

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

Object events

MinIO supports triggering notifications on the following S3 object events:

s3:ObjectAccessed:Get

data

s3:ObjectAccessed:GetLegalHold

data

s3:ObjectAccessed:GetRetention

data

s3:ObjectAccessed:Head

data

s3:ObjectCreated:CompleteMultipartUpload

data

s3:ObjectCreated:Copy

data

s3:ObjectCreated:DeleteTagging

data

s3:ObjectCreated:Post

data

s3:ObjectCreated:Put

data

s3:ObjectCreated:PutLegalHold

data

s3:ObjectCreated:PutRetention

data

s3:ObjectCreated:PutTagging

data

s3:ObjectRemoved:Delete

data

s3:ObjectRemoved:DeleteMarkerCreated

data

Specify the wildcard * character to select all events related to a prefix:

s3:ObjectAccessed:*

data

Selects all s3:ObjectAccessed -prefixed events.

s3:ObjectCreated:*

data

Selects all s3:ObjectCreated -prefixed events.

s3:ObjectRemoved:*

data

Selects all s3:ObjectRemoved -prefixed events.

Replication events

MinIO supports triggering notifications on the following S3 replication events:

s3:Replication:OperationCompletedReplication

data

s3:Replication:OperationFailedReplication

data

s3:Replication:OperationMissedThreshold

data

s3:Replication:OperationNotTracked

data

s3:Replication:OperationReplicatedAfterThreshold

data

Specify the wildcard * character to select all s3:Replication events:

s3:Replication:*

data

ILM transition events

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

s3:ObjectRestore:Post

data

s3:ObjectRestore:Completed

data

s3:ObjectTransition:Failed

data

s3:ObjectTransition:Complete

data

Specify the wildcard * character to select all events related to a prefix:

s3:ObjectTransition:*

data

Selects all s3:ObjectTransition -prefixed events.

s3:ObjectRestore:*

data

Selects all s3:ObjectRestore -prefixed events.

Scanner events

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

s3:Scanner:ManyVersions

data

Scanner finds objects with more than 1,000 versions.

s3:Scanner:BigPrefix

data

Scanner finds prefixes with more than 50,000 sub-folders.

Global events

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

s3:BucketCreated

data

s3:BucketRemoved

data

Payload schema

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"
    }
}

Example

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://minio.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"
      }
    }
  ]
}