API destinations as targets in Amazon EventBridge - Amazon EventBridge
Service-linked roleHeaders in requestsAPI destination error codesInvocation rate and event deliveryRegion availability
Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

API destinations as targets in Amazon EventBridge

EventBridge API destinations are HTTPS endpoints. You can invoke one as the target of an event bus rule or pipe, just as you invoke an AWS service or resource. With API destinations, you route events between AWS services, SaaS applications, and public or private applications. The events travel as API calls.

Note

The examples on this page use rules. A Custom Event Bus subscriber uses the same API destinations: set the API destination ARN as the subscriber's TargetArn with HttpParameters. See HTTP targets: API Gateway and API destinations.

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 in the rule or pipe. It 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 shape the event to fit a specific HTTP endpoint. For more information, see Amazon EventBridge input transformation.

To create a rule that sends events to an API destination, see Creating rules with API destination targets.

API destinations use a connection with authorization parameters to send events to HTTP endpoints.

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.

Note

EventBridge API destinations currently only support public domain names with publicly trusted certificates for HTTPS endpoints when using private APIs. API destinations do not support mutual TLS (mTLS).

Important

EventBridge requests to an API destination endpoint must have a maximum client execution timeout of 5 seconds. If the target endpoint takes longer than 5 seconds to respond, EventBridge times out the request. EventBridge retries timed-out requests. Your retry policy sets the maximums.

  • For event buses, by default the maximums are 24 hours and 185 times.

  • For pipes, the source type and its configuration determine the retries. EventBridge retries until the event expires from the source, or until it reaches the maximum event age or retry attempts.

After the maximum number of retries, events are sent to your dead-letter queue if you have one. Otherwise, the event is dropped.

Service-linked role for API destinations

When you create a connection for an API destination, the service-linked role AmazonEventBridgeApiDestinationsServiceRolePolicy is added to your account. EventBridge uses this 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 grants only the permissions the role needs to work with the connection secret. No other permissions are included. The role can work only with the connections in your account.

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

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.

Header key Header value

User-Agent

Amazon/EventBridge/ApiDestinations

Content-Type

If no custom Content-Type value is specified, EventBridge includes the following default value as Content-Type:

application/json; charset=utf-8

Range

bytes=0-1048575

Accept-Encoding

gzip,deflate

Connection

close

Content-Length

An entity header that indicates the size of the entity-body, in bytes, sent to the recipient.

Host

A request header that specifies the host and port number of the server where the request is being sent.

Headers that cannot be overridden in requests to API destinations

EventBridge does not allow you to override the following headers:

  • User-Agent

  • Range

Headers EventBridge removes from requests to API destinations

EventBridge removes the following headers for all API destination requests:

  • A-IM

  • Accept-Charset

  • Accept-Datetime

  • Accept-Encoding

  • Cache-Control

  • Connection

  • Content-Encoding

  • Content-Length

  • Content-MD5

  • Date

  • Expect

  • Forwarded

  • From

  • Host

  • HTTP2-Settings

  • If-Match

  • If-Modified-Since

  • If-None-Match

  • If-Range

  • If-Unmodified-Since

  • Max-Forwards

  • Origin

  • Pragma

  • Proxy-Authorization

  • Range

  • Referer

  • TE

  • Trailer

  • Transfer-Encoding

  • User-Agent

  • Upgrade

  • Via

  • Warning

API destination error codes

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

  • Retries events associated with error codes 401, 407, 409, 429, and 5xx.

  • Does not retry events associated with error codes 1xx, 2xx, 3xx, and 4xx (other than those noted above).

EventBridge API destinations read the standard HTTP response header Retry-After to learn how long to wait before the next 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 much lower than the number of invocations generated, events may not be delivered within the 24-hour retry window. For example, suppose you set the invocation rate to 10 per second, but thousands of events arrive each second. You will quickly build a backlog that exceeds 24 hours. To avoid losing events, set up a dead-letter queue for the failed invocations. You can process those events later. For more information, see Using dead-letter queues to process undelivered events in EventBridge.

Region availability

API destinations to public HTTPS endpoints are supported in the following AWS Regions:

  • US East (N. Virginia)

  • US East (Ohio)

  • US West (N. California)

  • US West (Oregon)

  • Africa (Cape Town)

  • Asia Pacific (Hong Kong)

  • Asia Pacific (Tokyo)

  • Asia Pacific (Seoul)

  • Asia Pacific (Osaka)

  • Asia Pacific (Mumbai)

  • Asia Pacific (Hyderabad)

  • Asia Pacific (Singapore)

  • Asia Pacific (Sydney)

  • Asia Pacific (Jakarta)

  • Canada (Central)

  • China (Beijing)

  • China (Ningxia)

  • Europe (Frankfurt)

  • Europe (Zurich)

  • Europe (Stockholm)

  • Europe (Milan)

  • Europe (Spain)

  • Europe (Ireland)

  • Europe (London)

  • Europe (Paris)

  • Middle East (UAE)

  • Middle East (Bahrain)

  • South America (São Paulo)