How do I invoke Lambda when a state (execution event) changes in Step Functions?

Last updated: 2019-08-30

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

Short Description

Use an Amazon CloudWatch Events rule to trigger a Lambda function that responds to an API call event change from a Step Functions state machine.


During this setup, make sure that:

  • The event change that you use to trigger the function is a supported API action.
  • You create the Step Functions state machine, Lambda function, and CloudWatch 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. Grant the IAM role permissions to perform any actions required for your use case. To have your state machine invoke your Lambda function, allow the action lambda:InvokeFunction.

Note: The managed policy AWSLambdaRole gives permissions to invoke Lambda functions.

2.    Create a Lambda execution role. 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.

Create and update a Lambda function

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's executed, the function just prints the event it receives. For example, if your Lambda function uses Python, you can use this code:

import json
def lambda_handler(event, context):
    print("Received event: " + json.dumps(event))

Create a CloudWatch Events rule

The rule that you create watches the Step Functions event pattern and invokes the Lambda function.

1.    Open the CloudWatch console.

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

3.    Choose Create rule.

4.    Under Event source, choose Event Pattern.

5.    For Service Name, choose Step Functions.

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

Note: You can also choose to have All Events for Step Functions trigger the rule. Or, you can choose AWS API Call via CloudTrail to trigger the rule for certain Step Functions API call events, such as StartExecution. For more information, see Creating a CloudWatch Events Rule That Triggers on an AWS API Call Using AWS CloudTrail.

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

8.    Under Targets, choose Add target. Confirm that Lambda function is the target type.

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

10.    Choose Configure details.

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

12.    For State, make sure that Enabled is selected.

13.    Choose Create rule.

For more information, see Creating a CloudWatch Events Rule That Triggers on an Event.

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 generated by your Lambda function.

4.    Verify the event details in the log stream.

Note: It might take a couple of minutes after you start execution for the log stream to appear.