S3 Events

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.

export default defineConfig(() => {
  const imagesBucket = new Bucket({});

  const processImage = new LambdaFunction({
    packaging: new JsBundleLambdaPackaging({
      entryfilePath: './src/process-image.ts'
    }),
    memory: 1024,
    timeout: 60,
    connectTo: [imagesBucket],
    events: [
      new S3Integration({
        bucketArn: $ResourceParam('imagesBucket', 'arn'),
        s3EventType: 's3:ObjectCreated:*',
        filterRule: {
          prefix: 'uploads/'
        }
      })
    ]
  });

  return {
    resources: { imagesBucket, processImage }
  };
});

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 typeFires when
s3:ObjectCreated:*Any object creation (Put, Post, Copy, multipart upload)
s3:ObjectCreated:PutObject created via PUT
s3:ObjectCreated:PostObject created via POST
s3:ObjectCreated:CopyObject created via COPY
s3:ObjectCreated:CompleteMultipartUploadMultipart upload completed
s3:ObjectRemoved:*Any object deletion
s3:ObjectRemoved:DeleteObject permanently deleted
s3:ObjectRemoved:DeleteMarkerCreatedDelete marker created (versioned bucket)
s3:ObjectRestore:*Any Glacier restore operation
s3:ObjectRestore:PostGlacier restore initiated
s3:ObjectRestore:CompletedGlacier restore completed
s3:Replication:*Any replication event
s3:Replication:OperationFailedReplicationReplication failed
s3:Replication:OperationNotTrackedObject not tracked by replication
s3:Replication:OperationMissedThresholdReplication exceeded the time threshold
s3:Replication:OperationReplicatedAfterThresholdObject replicated after time threshold
s3:ReducedRedundancyLostObjectObject 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.

events: [
  new S3Integration({
    bucketArn: $ResourceParam('dataBucket', 'arn'),
    s3EventType: 's3:ObjectCreated:*',
    filterRule: {
      prefix: 'imports/',
      suffix: '.csv'
    }
  })
]

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.

Use prefix filtering to prevent infinite loops. Place uploads into a dedicated key prefix (e.g. 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.

Object keys in the event payload are URL-encoded. Spaces appear as +, and special characters are percent-encoded. Always decode the key before using it to fetch the object from S3.
const handler = async (event: {
  Records: Array<{
    eventName: string;
    s3: {
      bucket: { name: string };
      object: { key: string; size: number };
    };
  }>;
}) => {
  for (const record of event.Records) {
    const bucketName = record.s3.bucket.name;
    const objectKey = decodeURIComponent(record.s3.object.key.replace(/\+/g, ' '));
    // Fetch and process the object using the AWS SDK
  }
};

export default handler;

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 to processed/. Set the filter rule's prefix to uploads/ so writes to processed/ do not trigger the function.
  • Suffix filtering. If uploads are .jpg and output is .webp, filter on suffix: '.jpg' so the .webp output does not match.
Infinite loops can generate thousands of Lambda invocations per second. If you suspect a loop, disable the bucket notification or remove the trigger immediately to stop new invocations.

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
Click a property in the tree to see its description, default value, and full type.