Skip to content

S3 - Event Notification

Amazon S3 invokes your function asynchronously with an event that contains details about the object.

Request

Event structure
{  
   "Records":[  
      {  
         "eventVersion":"2.2",
         "eventSource":"aws:s3",
         "awsRegion":"us-west-2",
         "eventTime":"The time, in ISO-8601 format, for example, 1970-01-01T00:00:00.000Z, when Amazon S3 finished processing the request",
         "eventName":"event-type",
         "userIdentity":{  
            "principalId":"Amazon-customer-ID-of-the-user-who-caused-the-event"
         },
         "requestParameters":{  
            "sourceIPAddress":"ip-address-where-request-came-from"
         },
         "responseElements":{  
            "x-amz-request-id":"Amazon S3 generated request ID",
            "x-amz-id-2":"Amazon S3 host that processed the request"
         },
         "s3":{  
            "s3SchemaVersion":"1.0",
            "configurationId":"ID found in the bucket notification configuration",
            "bucket":{  
               "name":"bucket-name",
               "ownerIdentity":{  
                  "principalId":"Amazon-customer-ID-of-the-bucket-owner"
               },
               "arn":"bucket-ARN"
            },
            "object":{  
               "key":"object-key",
               "size":"object-size in bytes",
               "eTag":"object eTag",
               "versionId":"object version if bucket is versioning-enabled, otherwise null",
               "sequencer": "a string representation of a hexadecimal value used to determine event sequence, only used with PUTs and DELETEs"
            }
         },
         "glacierEventData": {
            "restoreEventData": {
               "lifecycleRestorationExpiryTime": "The time, in ISO-8601 format, for example, 1970-01-01T00:00:00.000Z, of Restore Expiry",
               "lifecycleRestoreStorageClass": "Source storage class for restore"
            }
         }
      }
   ]
}

Request fields

Warning about records

Multiple records can be delivered in a single event

Record fields

eventVersion (String)
The eventVersion key value contains a major and minor version in the form <major>.<minor>
eventSource (String)
The AWS service from which the S3 event originated. For S3, this is aws:s3
awsRegion (String)
aws region eg: us-east-1
eventTime (String)
The time, in ISO-8601 format, for example, 1970-01-01T00:00:00.000Z, when S3 finished processing the request
eventName (String)
Event type. Supported event types eg: ObjectCreated:Put
userIdentity (Object)
Amazon customer ID of the user who caused the event
requestParameters (Object)
Contains sourceIPAddress of the request
responseElements (Object)
The responseElements key value is useful if you want to trace a request by following up with AWS Support. Both x-amz-request-id and x-amz-id-2 help Amazon S3 trace an individual request. These values are the same as those that Amazon S3 returns in the response to the request that initiates the events, so they can be used to match the event to the request.

S3 fields

s3SchemaVersion (String)
Should be '1.0' only
configurationId (String)
ID found in the bucket notification configuration
bucket (Object)
Details about the source S3 bucket
name (String)
S3 bucket name
ownerIdentity (Object)
Amazon customer ID of the user who owns the bucket
arn (String)
S3 Bucket ARN
object (Object)
S3 object / file that was created / modifieds
key (String)
The s3 key provides information about the bucket and object involved in the event.
TIP: object key

The s3 object key name value is URL encoded. For example, "red flower.jpg" becomes "red+flower.jpg". In python you would unquote_plus to decode this correct

size (Number)
Size of the object in bytes
eTag (String)
Etag of the object
versionId (String)
Object version if bucket is versioning-enabled, otherwise null
sequencer (String)
A string representation of a hexadecimal value used to determine event sequence, only used with PUTs and DELETEs

Generating sample events

sam local generate-event s3 put
sam local generate-event s3 delete

Request example

{
  "Records": [
    {
      "eventVersion": "2.1",
      "eventSource": "aws:s3",
      "awsRegion": "us-east-2",
      "eventTime": "2019-09-03T19:37:27.192Z",
      "eventName": "ObjectCreated:Put",
      "userIdentity": {
        "principalId": "AWS:AIDAINPONIXQXHT3IKHL2"
      },
      "requestParameters": {
        "sourceIPAddress": "205.255.255.255"
      },
      "responseElements": {
        "x-amz-request-id": "D82B88E5F771F645",
        "x-amz-id-2": "vlR7PnpV2Ce81l0PRw6jlUpck7Jo5ZsQjryTjKlc5aLWGVHPZLj5NeC6qMa0emYBDXOo6QBU0Wo="
      },
      "s3": {
        "s3SchemaVersion": "1.0",
        "configurationId": "828aa6fc-f7b5-4305-8584-487c791949c1",
        "bucket": {
          "name": "DOC-EXAMPLE-BUCKET",
          "ownerIdentity": {
            "principalId": "A3I5XTEXAMAI3E"
          },
          "arn": "arn:aws:s3:::lambda-artifacts-deafc19498e3f2df"
        },
        "object": {
          "key": "b21b84d653bb07b05b1e6b33684dc11b",
          "size": 1305107,
          "eTag": "b21b84d653bb07b05b1e6b33684dc11b",
          "sequencer": "0C0F6F405D6ED209E1"
        }
      }
    }
  ]
}

Response

N/A

Resources

Lambda Handlers

Code examples

Code examples using S3 bucket notifications

Python example decoding the object using unquote_plus

AWS Lambda Powertools for Python example
from urllib.parse import unquote_plus
from aws_lambda_powertools.utilities.data_classes import event_source, S3Event

@event_source(data_class=S3Event)
def lambda_handler(event: S3Event, context):
    bucket_name = event.bucket_name

    # Multiple records can be delivered in a single event
    for record in event.records:
        object_key = unquote_plus(record.s3.get_object.key)

        do_something_with(f"{bucket_name}/{object_key}")

Documentation