EventBridge (CloudWatch Events) for Step Functions execution status changes

Amazon EventBridge is an AWS service that enables you to respond to state changes in an AWS resource. You can use AWS Step Functions Standard Workflows with EventBridge, while Express Workflows do not emit events to EventBridge. There are two ways to use Step Functions Standard Workflows with EventBridge.

You can configure EventBridge rules to react to events that are emitted when the execution status of a Step Functions state machine changes. This enables you to monitor your workflows without having to constantly poll using the DescribeExecution API. Based on changes in state machine executions, you can use an EventBridge target to start new state machine executions, call AWS Lambda functions, publish messages to Amazon Simple Notification Service (Amazon SNS) topics, and more.

You can also configure a Step Functions state machine as a target in EventBridge. This enables you to trigger an execution of a Step Functions workflow in response to an event from another AWS service.

For more information, see the Amazon EventBridge User Guide .

EventBridge payloads

An EventBridge event can contain an input property in its definition. For some events, an EventBridge event can also contain an output property in its definition.

• If the combined escaped input and escaped output sent to EventBridge exceeds 248KB, then the input will be excluded. Similarly, if the escaped output exceeds 248KB, then the output will be excluded. This is a result of the EventBridge events quotas.

• You can determine whether a payload has been truncated with the inputDetails and outputDetails properties. For more information, see the CloudWatchEventsExecutionDataDetails Data Type.

• For Standard Workflows, you can see the full input and output by using DescribeExecution.

• DescribeExecution is not available for Express Workflows. If you want to see the full input/output, you can wrap your Express Workflow with a Standard Workflow. Another option is to use Amazon S3 ARNs. For information about using ARNs, see Use Amazon S3 ARNs instead of passing large payloads.

Step Functions event examples

The following are examples of Step Functions sending events to EventBridge:

Topics

• Execution started
• Execution succeeded
• Execution failed
• Execution timed out
• Execution aborted

In each case, the detail section in the event data provides the same information as the DescribeExecution API. The status field indicates the status of the execution at the time the event was sent, one of RUNNING, SUCCEEDED, FAILED, TIMED_OUT, or ABORTED depending on the event emitted.

Execution started

{
    "version": "0",
    "id": "315c1398-40ff-a850-213b-158f73e60175",
    "detail-type": "Step Functions Execution Status Change",
    "source": "aws.states",
    "account": "012345678912",
    "time": "2019-02-26T19:42:21Z",
    "region": "us-east-1",
    "resources": [
      "arn:aws:states:us-east-1:012345678912:execution:state-machine-name:execution-name"
    ],
    "detail": {
        "executionArn": "arn:aws:states:us-east-1:012345678912:execution:state-machine-name:execution-name",
        "stateMachineArn": "arn:aws:states:us-east-1:012345678912:stateMachine:state-machine",
        "name": "execution-name",
        "status": "RUNNING",
        "startDate": 1551225271984,
        "stopDate":  null,
        "input": "{}",
        "inputDetails": {
             "included": true
        },
        "output": null,
        "outputDetails": null
    }
}

Execution succeeded

{
    "version": "0",
    "id": "315c1398-40ff-a850-213b-158f73e60175",
    "detail-type": "Step Functions Execution Status Change",
    "source": "aws.states",
    "account": "012345678912",
    "time": "2019-02-26T19:42:21Z",
    "region": "us-east-1",
    "resources": [
      "arn:aws:states:us-east-1:012345678912:execution:state-machine-name:execution-name"
    ],
    "detail": {
        "executionArn": "arn:aws:states:us-east-1:012345678912:execution:state-machine-name:execution-name",
        "stateMachineArn": "arn:aws:states:us-east-1:012345678912:stateMachine:state-machine",
        "name": "execution-name",
        "status": "SUCCEEDED",
        "startDate": 1547148840101,
        "stopDate": 1547148840122,
        "input": "{}",
        "inputDetails": {
             "included": true
        },
        "output": "\"Hello World!\"",
        "outputDetails": {
             "included": true
        }
    }
}

Execution failed

{
    "version": "0",
    "id": "315c1398-40ff-a850-213b-158f73e60175",
    "detail-type": "Step Functions Execution Status Change",
    "source": "aws.states",
    "account": "012345678912",
    "time": "2019-02-26T19:42:21Z",
    "region": "us-east-1",
    "resources": [
      "arn:aws:states:us-east-1:012345678912:execution:state-machine-name:execution-name"
    ],
    "detail": {
        "executionArn": "arn:aws:states:us-east-1:012345678912:execution:state-machine-name:execution-name",
        "stateMachineArn": "arn:aws:states:us-east-1:012345678912:stateMachine:state-machine",
        "name": "execution-name",
        "status": "FAILED",
        "startDate": 1551225146847,
        "stopDate": 1551225151881,
        "input": "{}",
        "inputDetails": {
             "included": true
        },
        "output": null,
        "outputDetails": null
    }
}

Execution timed out

{
    "version": "0",
    "id": "315c1398-40ff-a850-213b-158f73e60175",
    "detail-type": "Step Functions Execution Status Change",
    "source": "aws.states",
    "account": "012345678912",
    "time": "2019-02-26T19:42:21Z",
    "region": "us-east-1",
    "resources": [
      "arn:aws:states:us-east-1:012345678912:execution:state-machine-name:execution-name"
    ],
    "detail": {
        "executionArn": "arn:aws:states:us-east-1:012345678912:execution:state-machine-name:execution-name",
        "stateMachineArn": "arn:aws:states:us-east-1:012345678912:stateMachine:state-machine",
        "name": "execution-name",
        "status": "TIMED_OUT",
        "startDate": 1551224926156,
        "stopDate": 1551224927157,
        "input": "{}",
        "inputDetails": {
             "included": true
        },
        "output": null,
        "outputDetails": null
    }
}

Execution aborted

{
    "version": "0",
    "id": "315c1398-40ff-a850-213b-158f73e60175",
    "detail-type": "Step Functions Execution Status Change",
    "source": "aws.states",
    "account": "012345678912",
    "time": "2019-02-26T19:42:21Z",
    "region": "us-east-1",
    "resources": [
      "arn:aws:states:us-east-1:012345678912:execution:state-machine-name:execution-name"
    ],
    "detail": {
        "executionArn": "arn:aws:states:us-east-1:012345678912:execution:state-machine-name:execution-name",
        "stateMachineArn": "arn:aws:states:us-east-1:012345678912:stateMachine:state-machine",
        "name": "execution-name",
        "status": "ABORTED",
        "startDate": 1551225014968,
        "stopDate": 1551225017576,
        "input": "{}",
        "inputDetails": {
             "included": true
        },
        "output": null,
        "outputDetails": null
    }
}

Routing a Step Functions event to EventBridge in the EventBridge console

Use the following instructions to learn how to trigger the execution of a Step Functions state machine whenever a specific Step Functions state machine completes running successfully. You use the Amazon EventBridge console to specify the state machine whose execution you want to trigger.

1. On the Details page of a state machine, choose Actions, and then choose Create EventBridge (CloudWatch Events) rule.

   

   Alternatively, open the EventBridge console at https://console.aws.amazon.com/events/. In the navigation pane, choose Rules under Events.

2. Choose Create rule.

3. Enter a Name for your rule (for example, StepFunctionsEventRule) and optionally enter a Description for the rule.

4. For Event bus and Rule type, keep the default selections.

5. Choose Next.

6. Under Event Source, keep the default selection of AWS events or EventBridge partner events.

7. Under Event pattern, do the following:

   1. In the Event source dropdown list, keep the default selection of AWS services.

   2. From the AWS service dropdown list, choose Step Functions.

   3. From the Event Type dropdown list, choose Step Functions Execution Status Change.

   4. (Optional) Configure a specific status, state machine Amazon Resource Name (ARN), or execution ARN. For this procedure, choose Specific status(es), and then choose SUCCEEDED from the dropdown list.

8. Choose Next.

9. On the Select target(s) page, keep the default selection of AWS service.

10. From the Select a target dropdown list, choose an AWS service. For example, you could launch a Lambda function, or run a Step Functions state machine. For this procedure, choose Step Functions state machine.

11. From the State machine dropdown list, choose a state machine.

12. Under Execution role, keep the default selection of Create a new role for this specific resource.

13. Choose Next, and then choose Next again.

14. On the Review and create page, review the details of the rule and choose Create rule.

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