How do I set up a Lambda function to invoke when a state (execution event) changes in AWS Step Functions?

Last updated: 2021-04-05

I want to invoke an AWS Lambda function whenever a state (execution event) changes in AWS Step Functions. How do I do that?


Note: These instructions describe how to use an Amazon EventBridge events rule to invoke a Lambda function whenever a state changes in Step Functions. As you follow the steps, make sure that you do the following:

  • Confirm the event change that you use to invoke the Lambda function is a supported API action.
  • Create the Step Functions state machine, Lambda function, and EventBridge events rule in the same AWS Region.

Create IAM roles for Step Functions and Lambda

1.    Create an AWS Identity and Access Management (IAM) role for Step Functions. When you create the IAM role, do the following:
Grant the IAM role permissions to perform any actions required for your use case.
Allow the action, lambda:InvokeFunction, to have your state machine invoke your Lambda function.
Note: The managed policy, AWSLambdaRole, includes the permissions required to invoke Lambda functions.

2.    Create a Lambda execution role that grants your function permission to upload logs to Amazon CloudWatch.
Note: The managed policy, AWSLambdaBasicExecutionRole, grants your function the basic permissions to upload logs to CloudWatch.

Create a Step Functions state machine

Create a state machine in the Step Functions console. For IAM role for executions, choose the existing role that you created for Step Functions.

For more information, see What is AWS Step Functions?

Create a Lambda function that's configured to print the event it receives

1.    Create a function in the Lambda console. For Execution role, choose the existing role that you created for Lambda.

2.    In the Lambda console, use the code editor to update the function code so that when it runs, the function prints the event that it receives.

Example Python code that tells a Lambda function to print the events it receives

import json

def lambda_handler(event, context):
print("Received event: " + json.dumps(event)) return {
'statusCode': 200,
'body': json.dumps("Hello")

For more information, see Building Lambda functions with Python.

Create an EventBridge events rule that invokes your Lambda function whenever a state changes in Step Functions

1.    Open the EventBridge console.

2.    In the left navigation pane, under Events, choose Rules.

3.    Choose Create rule.

4.    For Name, enter a name for the rule.

5.    For Define pattern, choose Event Pattern.

6.    For Event matching pattern, choose Pre-defined pattern by service.

7.    For Service provider, choose AWS.

8.    For Service Name, choose Step Functions.

9.    For Event Type, choose Step Functions Execution Status Change.

Note: You can also choose to have All Events for Step Functions initiate the rule. Or, you can choose AWS API Call via CloudTrail to initiate the rule for certain Step Functions API call events, such as StartExecution. For more information, see Events delivered via CloudTrail.

10.    Choose the statuses, state machine Amazon Resource Names (ARNs), and execution ARNs that you want to initiate the event. You can choose Any for each type of trigger, or identify Specific statuses or ARNs for each trigger.

11.    Under Select targets, confirm that Lambda function is the target type.

12.    For Function, choose the Lambda function that you created

13.    Choose Create rule.

For more information, see Amazon EventBridge events and EventBridge for Step Functions execution status changes.

Test your setup

1.    In the Step Functions console, start a new execution of your state machine.

2.    In the CloudWatch console, in the left navigation pane, choose Logs.

3.    Choose the log stream created by your Lambda function.

4.    Verify the event details in the log stream.

Note: It can take several minutes for the log stream to appear after the new execution starts.