Add EventBridge events with Step Functions - Amazon Step Functions
Supported EventBridge APIError handling
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 (PDF).

Add EventBridge events with Step Functions

Step Functions provides a service integration API for integrating with Amazon EventBridge. Learn how to build event-driven applications by sending custom events directly from Step Functions workflows.

Step Functions can control certain Amazon services directly from Using Amazon States Language to define Step Functions workflows (ASL). To learn more, see Integrating other services and Passing parameters to a service API in Step Functions.

How the Optimized EventBridge integration is different than the EventBridge Amazon SDK integration

  • The execution ARN and the state machine ARN are automatically appended to the Resources field of each PutEventsRequestEntry.

  • If the response from PutEvents contains a non-zero FailedEntryCount then the Task state fails with the error EventBridge.FailedEntry.

For information about how to configure IAM permissions when using Step Functions with other Amazon services, see How Step Functions generates IAM policies for integrated services.

To use the PutEvents API, you will need to create an EventBridge rule in your account that matches the specific pattern of the events you will send. For example, you could:

  • Create a Lambda function in your account that receives and prints an event that matches an EventBridge rule.

  • Create an EventBridge rule in your account on the default event bus that matches a specific event pattern and targets the Lambda function.

For more information, see:

Note

There is a quota for the maximum input or result data size for a task in Step Functions. This restricts you to 256 KB of data as a UTF-8 encoded string when you send to, or receive data from, another service. See Quotas related to state machine executions.

Supported EventBridge API

Supported EventBridge API and syntax include:

The following includes a Task that sends a custom event:

{
  "Type": "Task",
  "Resource": "arn:aws:states:::events:putEvents",
  "Parameters": {
    "Entries": [
      {
        "Detail": {
          "Message": "MyMessage"
        },
        "DetailType": "MyDetailType",
        "EventBusName": "MyEventBus",
        "Source": "my.source"
      }
    ]
  },
  "End": true
}

Error handling

The PutEvents API accepts an array of entries as input, then returns an array of result entries. As long as the PutEvents action was successful, PutEvents will return an HTTP 200 response, even if one or more entries failed. PutEvents returns the number of failed entries in the FailedEntryCount field.

Step Functions checks whether the FailedEntryCount is greater than zero. If it is greater than zero, Step Functions fails the state with the error EventBridge.FailedEntry. This lets you use the built-in error handling of Step Functions on task states to catch or retry when there are failed entries, rather than needing to use an additional state to analyze the FailedEntryCount from the response.

Note

If you have implemented idempotency and can safely retry on all entries, you can use Step Functions' retry logic. Step Functions does not remove successful entries from the PutEvents input array before retrying. Instead, it retries with the original array of entries.