API destinations as targets in Amazon EventBridge

EventBridge API destinations are HTTPS endpoints that you can invoke as the target of an event bus rule, or pipe, similar to how you invoke an AWS service or resource as a target. Using API destinations, you can route events between AWS services, integrated software as a service (SaaS) applications, and public or private applications by using API calls.

When you specify an API destination as a rule or pipe target, EventBridge invokes the HTTPS endpoint for any event that matches the event pattern specified in the rule or pipe and then delivers the event information with the request. With EventBridge, you can use any HTTP method except CONNECT and TRACE for the request. The most common HTTP methods to use are PUT and POST.

You can also use input transformers to customize the event to the parameters of a specific HTTP endpoint parameters. For more information, see Amazon EventBridge input transformation.

EventBridge API destinations use connections to define the authorization method and credentials and network connectivity for EventBridge to use when connecting to a given HTTPS endpoint. Connections support both public and private APIs. For more information, see Connections.

The following video demonstrates the use of API destination:

Service-linked role for API destinations

When you create a connection for an API destination, a service-linked role named AWSServiceRoleForAmazonEventBridgeApiDestinations is added to your account. EventBridge uses the service-linked role to create and store a secret in Secrets Manager. To grant the necessary permissions to the service-linked role, EventBridge attaches the AmazonEventBridgeApiDestinationsServiceRolePolicy policy to the role. The policy limits the permissions granted to only those necessary for the role to interact with the secret for the connection. No other permissions are included, and the role can interact only with the connections in your account to manage the secret.

The following policy is the AmazonEventBridgeApiDestinationsServiceRolePolicy.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "secretsmanager:CreateSecret",
                "secretsmanager:UpdateSecret",
                "secretsmanager:DescribeSecret",
                "secretsmanager:DeleteSecret",
                "secretsmanager:GetSecretValue",
                "secretsmanager:PutSecretValue"
            ],
            "Resource": "arn:aws:secretsmanager:*:*:secret:events!connection/*"
        }
    ]
}

For more information about service-linked roles, see Using service-linked roles in the IAM User Guide.

Region availability

The AmazonEventBridgeApiDestinationsServiceRolePolicy service-linked role is supported in the following AWS regions:

Headers in requests to API destinations

The following section details how EventBridge handles HTTP headers in requests to API destinations.

Headers included in requests to API destinations

In addition to the authorization headers defined for the connection used for an API destination, EventBridge includes the following headers in each request.

Headers that cannot be overridden in requests to API destinations

EventBridge does not allow you to override the following headers:

Headers EventBridge removes from requests to API destinations

EventBridge removes the following headers for all API destination requests:

API destination error codes

When EventBridge tries to deliver an event to an API destination and an error occurs, EventBridge does the following:

EventBridge API destinations read the standard HTTP response header Retry-After to find out how long to wait before making a follow-up request. For event buses, EventBridge chooses the more conservative value between the defined retry policy and the Retry-After header. If Retry-After value is negative, EventBridge stops retrying delivery for that event.

How invocation rate affects event delivery

If you set the invocation rate per second to a value much lower than the number of invocations generated, events may not be delivered within the 24 hour retry time for events. For example, if you set the invocation rate to 10 invocations per second, but thousands of events per second are generated, you will quickly have a backlog of events to deliver that exceeds 24 hours. To ensure that no events are lost, set up a dead-letter queue to send events with failed invocations to so you can process the events at a later time. For more information, see Using dead-letter queues to process undelivered events in EventBridge.