Starting a State Machine Execution in Response to Amazon S3 Events - Amazon Step Functions
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Starting a State Machine Execution in Response to Amazon S3 Events

You can use Amazon EventBridge to execute an Amazon Step Functions state machine in response to an event or on a schedule.

This tutorial shows you how to configure a state machine as a target for a Amazon EventBridge rule. This will start an execution when files are added to an Amazon S3 bucket.

For a practical application, you could launch a state machine that performs operations on files that you add to the bucket, such as creating thumbnails or running Amazon Rekognition analysis on image and video files.

For this tutorial you start an execution of a simple Helloworldstate machine by adding a file to an Amazon Simple Storage Service (Amazon S3) bucket. Then you review example input of that execution to show what information is included in the input from Amazon CloudTrail.

Prerequisite: Create a State Machine

Before you can configure a Amazon EventBridge target, you must create a state machine.

  • To create a basic state machine, use the Getting Started tutorial.

  • If you already have a Helloworldstate machine, proceed to the next step.

Step 1: Create a Bucket in Amazon S3

Now that you have a Helloworld state machine, you need an Amazon S3 bucket. In Step 3 of this tutorial, you set up a rule so that when a file is added to this bucket, Amazon EventBridge triggers an execution of the state machine.

  1. Navigate to the Amazon S3 console, and then choose Create bucket.

  2. Enter a Bucket name, such as username-sfn-tutorial.


    Bucket names must be unique across all existing bucket names in all Amazon Regions in Amazon S3. Use your own username to make this name unique. You need to create all resources in the same Amazon Region.

  3. Choose Create.

Step 2: Create a Trail in Amazon CloudTrail

After you create an Amazon S3 bucket, create a trail in CloudTrail.

For API events in Amazon S3 to match your Amazon EventBridge rule, you must configure a trail in CloudTrail to receive those events.

  1. Open the Amazon CloudTrail console.

  2. Choose Trails, and then choose Create trail.

  3. For Trail name, enter S3Event.

  4. Choose Use existing S3 bucket.

  5. For Trail log bucket name, enter the name of the Amazon S3 bucket you created earlier: username-sfn-tutorial (Step 1: Create a Bucket in Amazon S3).

  6. Select Enabled in Log file SSE-KMS encryption to disable encryption.


    You can optionally choose to enable encryption in Log file SSE-KMS encryption, and enter any name in Amazon KMS alias to create a key.

  7. Choose Next, Next, Create trail.

Step 3: Create a Amazon EventBridge Rule

After you have a state machine, and have created the Amazon S3 bucket and a trail in Amazon CloudTrail, create your Amazon EventBridge rule.


You must configure Amazon EventBridge in the same Amazon Region as the Amazon S3 bucket.

To create the rule

  1. Navigate to the Amazon EventBridge console, choose Create rule.

  2. In Define pattern, choose Event pattern.

  3. In Event matching pattern, choose Pre-defined pattern by service.

  4. In Service provider, choose Amazon.

  5. In Service name, choose Simple Storage Service (S3).

  6. For Event type, choose Object Level Operations.

  7. Choose Specific operation(s), and then choose PutObject.


    If the object size is bigger than the Multipart threshold used in the PutObject operation, the Amazon CloudTrail API logged will be CompleteMultipartUpload instead of PutObject. See, Multipart Upload Overview in the Amazon CloudTrail User Guide.

  8. Choose Specific bucket(s) by name and enter the bucket name you created in Step 1 (username-sfn-tutorial).

To create the target

  1. Choose Step Functions state machine in the dropdown list, and in the State machine list, choose the state machine from Step 1 (Helloworld).

  2. Amazon EventBridge can create the IAM role that your event needs to run:

    • To create an IAM role automatically, choose Create a new role for this specific resource.

    • To use an IAM role that you created before, choose Use existing role.

  3. Choose Create.

  4. Enter a Name for your rule (for example, S3StepFunctions), choose Enabled for State, and then choose Create rule.

    The Configure rule details section should look like the following.

                            Configure rule details

    The rule is created and the Rules page is displayed, listing all your Amazon EventBridge rules.

Step 4: Test the Rule

Now that everything is in place, test adding a file to the Amazon S3 bucket, and then look at the input of the resulting state machine execution.

  1. Add a file to your Amazon S3 bucket.

    Navigate to the Amazon S3 console, select the bucket you created (username-sfn-tutorial), and then choose Upload.

  2. Add a file (test.png in the following example), and then choose Upload.

    This launches an execution of your state machine, passing information from Amazon CloudTrail as the input.

  3. Check the execution for your state machine.

    Navigate to the Step Functions console and select the state machine used in your Amazon EventBridge rule (Helloworld).

  4. Select the most recent execution of that state machine and expand the Input section.

    This input includes information such as the bucket name and the object name. In a real-world use case, a state machine can use this input to perform actions on that object.

Example of Execution Input

The following example shows typical input to the state machine execution.

{ "version": "0", "id": "8d6f9246-b781-44f8-a026-f1c1ab2c61f0", "detail-type": "AWS API Call via CloudTrail", "source": "aws.s3", "account": "123456789012", "time": "2018-09-12T00:25:10Z", "region": "us-east-2", "resources": [], "detail": { "eventVersion": "1.05", "userIdentity": { "type": "IAMUser", "principalId": "AKIAIOSFODNN7EXAMPLE", "arn": "arn:aws:iam::123456789012:user/username", "accountId": "123456789012", "accessKeyId": "AKIAI44QH8DHBEXAMPLE", "userName": "username", "sessionContext": { "attributes": { "creationDate": "2018-09-11T20:10:38Z", "mfaAuthenticated": "true" } }, "invokedBy": "" }, "eventTime": "2018-09-12T00:25:10Z", "eventSource": "", "eventName": "PutObject", "awsRegion": "us-east-2", "sourceIPAddress": "", "userAgent": "", "requestParameters": { "X-Amz-Date": "20180912T002509Z", "bucketName": "username-sfn-tutorial", "X-Amz-Algorithm": "AWS4-HMAC-SHA256", "x-amz-acl": "private", "X-Amz-SignedHeaders": "content-type;host;x-amz-acl;x-amz-storage-class", "X-Amz-Expires": "300", "key": "test.png", "x-amz-storage-class": "STANDARD" }, "responseElements": null, "additionalEventData": { "x-amz-id-2": "IOWQ4fDEXAMPLEQM+ey7N9WgVhSnQ6JEXAMPLEZb7hSQDASK+Jd1vEXAMPLEa3Km" }, "requestID": "79104EXAMPLEB723", "eventID": "cdc4b7ed-e171-4cef-975a-ad829d4123e8", "readOnly": false, "resources": [ { "type": "AWS::S3::Object", "ARN": "arn:aws:s3:::username-sfn-tutorial-2/test.png" }, { "accountId": "123456789012", "type": "AWS::S3::Bucket", "ARN": "arn:aws:s3:::username-sfn-tutorial" } ], "eventType": "AwsApiCall", "recipientAccountId": "123456789012" } }