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 AWS services directly from Amazon States Language (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 AWS SDK integration
-
The execution ARN and the state machine ARN are automatically appended to the
Resources
field of eachPutEventsRequestEntry
. -
If the response from
PutEvents
contains a non-zeroFailedEntryCount
then theTask
state fails with the errorEventBridge.FailedEntry
.
For information about how to configure IAM permissions when using Step Functions with other AWS 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:
-
Adding Amazon EventBridge events with PutEvents in the EventBridge User Guide.
-
Wait for a Callback with the Task Token in Service Integration Patterns.
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:
-
-
Supported parameter:
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.