API destinations - Amazon EventBridge
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).

API destinations

Amazon EventBridge API destinations are HTTP endpoints that you can invoke as the target of a rule, similar to how you invoke an Amazon service or resource as a target. Using API destinations, you can route events between Amazon services, integrated software as a service (SaaS) applications, and your applications outside of Amazon by using API calls. When you specify an API destination as the target of a rule, EventBridge invokes the HTTP endpoint for any event that matches the event pattern specified in the rule 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.

API destinations do not support private destinations, such as interface VPC endpoints. For more information, see Using Amazon EventBridge with Interface VPC Endpoints .

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 up to the maximums that are configured on your retry policy. By default the maximums are 24 hours and 185 times. After the maximum number of retries, events are sent to your dead-letter queue if you have one.Otherwise, the event is dropped.

The following video demonstrates the use of API destination:

Create an API destination

Each API destination requires a connection. A connection specifies the authorization type and credentials to use to authorize with the API destination endpoint. You can choose an existing connection, or create a connection at the same time that you create the API destination. For more information, see Connections for HTTP endpoint targets

To create an API destination using the EventBridge console
  1. Log in to Amazon using an account that has permissions to manage EventBridge and open the EventBridge console.

  2. In the left navigation pane, choose API destinations.

  3. Scroll down to the API destinations table, and then choose Create API destination.

  4. On the Create API destination page, enter a Name for the API destination. You can use up to 64 uppercase or lowercase letters, numbers, dot (.), dash (-), or underscore (_) characters.

    The name must be unique to your account in the current Region.

  5. Enter a Description for the API destination.

  6. Enter an API destination endpoint for the API destination. The API destination endpoint is an HTTP invocation endpoint target for events. The authorization information you include in the connection used for this API destination is used to authorize against this endpoint. The URL must use HTTPS.

  7. Enter the HTTP method to use to connect to the API destination endpoint.

  8. (Optional) For Invocation rate limit per second field, enter the maximum number of invocations per second to send to the API destination endpoint.

    The rate limit you set may affect how EventBridge delivers events. For more information, see How invocation rate affects event delivery.

  9. For Connection, do one of the following:

    • Choose Use an existing connection, and then select the connection to use for this API destination.

    • Choose Create a new connection, and then enter the details for the connection to create. For more information, see Connections.

  10. Choose Create.

Creating rules that send events to an API destination

After you create an API destination, you can select it as the target of a rule. To use an API destination as a target, you must provide an IAM role with the correct permissions. For more information, see Permissions required for EventBridge to access targets using IAM roles

Selecting an API destination as a target is part of creating the rule.

To create a rule that sends events to an API destination using the console
  1. Follow the steps in the Creating Amazon EventBridge rules that react to events procedure.

  2. In the Select targets step, when prompted to choose an API destination as the target type:

    1. Select EventBridge API destination.

    2. Do one of the following:

      • Choose Use an existing API destination and select an existing API destination

      • Choose Create a new API destination and specify the necessary setting to define your new API destination.

        For more information on specifying the required settings, see Create an API destination.

    3. (Optional): To specify header parameters for the event, under Header Parameters choose Add header parameter.

      Next, specify the key and value for the header parameter.

    4. (Optional): To specify query string parameters for the event, under Query string parameters choose Add query string parameter.

      Next, specify the key and value for the query string parameter.

  3. Complete creating the rule following the procedure steps.

Service-linked role for API destinations

When you create a connection for an API destination, a service-linked role named AmazonServiceRoleForAmazonEventBridgeApiDestinations 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 documentation.

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

  • US East (N. Virginia)

  • US East (Ohio)

  • US West (N. California)

  • US West (Oregon)

  • Africa (Cape Town)

  • Asia Pacific (Hong Kong)

  • Asia Pacific (Mumbai)

  • Asia Pacific (Osaka)

  • Asia Pacific (Seoul)

  • Asia Pacific (Singapore)

  • Asia Pacific (Sydney)

  • Asia Pacific (Tokyo)

  • Canada (Central)

  • Europe (Frankfurt)

  • Europe (Ireland)

  • Europe (London)

  • Europe (Milan)

  • Europe (Paris)

  • Europe (Stockholm)

  • Europe (Milan)

  • South America (São Paulo)

  • China (Ningxia)

  • China (Beijing)

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:

  • Events associated with error codes 409, 429, and 5xx are retried.

  • Events associated with error codes 1xx, 2xx, 3xx, and 4xx (excluding 429) aren't retried.

EventBridge API destinations read the standard HTTP response header Retry-After to find out how long to wait before making a follow-up request. 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 Event retry policy and using dead-letter queues.