Call EventBridge 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).

Call EventBridge with Step Functions

Step Functions can control certain Amazon services directly from Amazon States Language (ASL). To learn more, see Working with other services and Pass parameters to a service API.

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 IAM Policies for integrated services.

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

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.