An S3 event trigger invokes a Lambda function or batch job when objects are created, deleted, or restored in an S3 bucket. S3 triggers are the standard approach for event-driven file processing — image resizing, data imports, log parsing, virus scanning — without polling or idle infrastructure costs. S3 events are configured by adding an S3Integration to the events array of a Lambda function or batch job.
When to use
S3 event triggers eliminate polling. Instead of periodically checking a bucket for new files, the function runs automatically when a qualifying event occurs. AWS charges only for the invocations that actually run — there is no idle cost. Use S3 triggers whenever your workflow needs to react to file changes as they happen.
Common use cases include:
- Image processing — resize, crop, or convert images on upload
- Data ingestion — parse CSV, JSON, or Parquet files into a database
- File validation — scan uploads for viruses or verify file formats
- Notifications — send a message when a report or export is generated
When not to use
S3 event triggers are not the right fit when you need to aggregate multiple uploads before processing. An SQS queue between S3 and your consumer gives you batching control and decouples the upload rate from processing throughput.
If the same bucket needs to fan out events to multiple independent consumers, an AWS architecture pattern is to route S3 notifications through an intermediary like SNS or EventBridge so each consumer can subscribe independently.
Basic example
This example creates a bucket and a Lambda function that triggers whenever a new object is uploaded under the uploads/ prefix.
The bucketArn property is the ARN of the S3 bucket to monitor. For a bucket defined in the same Stacktape config, use $ResourceParam to resolve the ARN at deploy time — for example, $ResourceParam('imagesBucket', 'arn'). bucketArn is typed as a string, so the property also accepts a literal ARN for buckets managed outside the current config.
The example uses connectTo: [imagesBucket] to wire the Lambda function to the bucket. See Connecting resources for the permissions and environment variables connectTo provides.
Event types
The s3EventType property determines which bucket operations trigger the function. The following S3 event notification types are supported:
| Event type | Fires when |
|---|---|
s3:ObjectCreated:* | Any object creation (Put, Post, Copy, multipart upload) |
s3:ObjectCreated:Put | Object created via PUT |
s3:ObjectCreated:Post | Object created via POST |
s3:ObjectCreated:Copy | Object created via COPY |
s3:ObjectCreated:CompleteMultipartUpload | Multipart upload completed |
s3:ObjectRemoved:* | Any object deletion |
s3:ObjectRemoved:Delete | Object permanently deleted |
s3:ObjectRemoved:DeleteMarkerCreated | Delete marker created (versioned bucket) |
s3:ObjectRestore:* | Any Glacier restore operation |
s3:ObjectRestore:Post | Glacier restore initiated |
s3:ObjectRestore:Completed | Glacier restore completed |
s3:Replication:* | Any replication event |
s3:Replication:OperationFailedReplication | Replication failed |
s3:Replication:OperationNotTracked | Object not tracked by replication |
s3:Replication:OperationMissedThreshold | Replication exceeded the time threshold |
s3:Replication:OperationReplicatedAfterThreshold | Object replicated after time threshold |
s3:ReducedRedundancyLostObject | Object in Reduced Redundancy storage lost |
For most use cases, s3:ObjectCreated:* is the right default — it covers all creation paths regardless of how the object was uploaded. Use a more specific type (e.g. s3:ObjectCreated:Put) only when you need to distinguish between creation methods.
Filtering events
The optional filterRule property narrows which objects trigger the function based on the object key. You can specify a prefix, a suffix, or both. When both are set, an object must match both conditions.
The prefix filter matches the beginning of the object key — prefix: 'imports/' triggers only for objects whose key starts with imports/. The suffix filter matches the end — suffix: '.csv' triggers only for CSV files. These filters keep your function focused and prevent it from processing irrelevant objects.
uploads/, incoming/) and write output to a separate prefix (e.g. processed/). This ensures the function's output does not re-trigger itself.Event payload
The Lambda function receives the standard AWS S3 event notification payload. Each invocation carries a Records array where each record describes one S3 event — including the bucket name, object key, event type, and object size.
+, and special characters are percent-encoded. Always decode the key before using it to fetch the object from S3.This is the standard AWS S3 event notification shape. For the full payload reference, consult the AWS S3 event message structure documentation.
Delivery and retries
AWS S3 delivers event notifications asynchronously. The S3Integration type configures only three properties: bucketArn, s3EventType, and filterRule. It does not expose batchSize, maxBatchWindowSeconds, retry, failure-destination, or dead-letter settings.
Retry behavior is handled at the AWS Lambda layer, not by Stacktape's S3Integration. Under AWS Lambda's asynchronous invocation defaults, if the function returns an error, AWS retries the invocation twice (three attempts total).
AWS S3 event notifications provide at-least-once delivery. In rare cases, a single event may trigger the function more than once. Design your handler to be idempotent — processing the same file twice should produce the same result.
Avoiding infinite loops
A common mistake: the Lambda function reads an object from the bucket, processes it, and writes the result back to the same bucket without a filter rule to exclude the output. The write triggers the function again, creating an infinite loop that runs up your AWS bill.
Prevent this with one of these strategies:
- Separate output bucket. Write processed files to a different bucket entirely. This is the safest approach and the one to prefer when cost and complexity are not concerns.
- Prefix separation. Read from
uploads/and write toprocessed/. Set the filter rule'sprefixtouploads/so writes toprocessed/do not trigger the function. - Suffix filtering. If uploads are
.jpgand output is.webp, filter onsuffix: '.jpg'so the.webpoutput does not match.
S3 Events FAQ
Can I trigger multiple Lambda functions from the same bucket?
S3 notification rules can conflict when multiple consumers use overlapping event types and prefix/suffix filters on the same bucket. For multiple independent consumers, prefer routing bucket events through SNS or EventBridge so each consumer subscribes independently.
Is S3 event delivery guaranteed exactly once?
No. AWS S3 event notifications provide at-least-once delivery. In rare cases, a single event can be delivered more than once. Make your handler idempotent — for example, check whether the output file already exists before processing, or use a deduplication key in a database.
What happens if my Lambda function fails processing an S3 event?
S3Integration configures only bucketArn, s3EventType, and filterRule — it does not expose retry or failure-destination settings. Retry behavior is handled by AWS Lambda's asynchronous invocation defaults: AWS retries the invocation twice (three total attempts).
Can I filter S3 events by object size or content type?
No. The filterRule property supports only key prefix and suffix matching. If you need to filter by object metadata, size, or content type, accept all matching events in the Lambda function and add conditional logic at the start of your handler to skip objects that do not meet your criteria.
When should I use S3 events vs polling with SQS?
S3 event triggers react to individual file operations immediately — the event arrives within seconds and requires no polling infrastructure. Use SQS as an intermediary when you need batching (process 10 files at once), controlled concurrency, or a buffer between bursty uploads and a downstream system that processes at a fixed rate.
How much does S3 event-driven processing cost?
The main costs in this pattern are the Lambda invocations and any S3 API calls your handler makes (GET, PUT). You pay per Lambda request plus compute duration — there is no idle infrastructure cost. This makes S3-triggered Lambda a cost-effective pattern for variable or bursty workloads.
API reference
S3IntegrationProps