AWS::Events::ApiDestination - AWS CloudFormation
SyntaxPropertiesReturn valuesExamples

AWS::Events::ApiDestination

Creates an API destination, which is an HTTP invocation endpoint configured as a target for events.

When using ApiDesinations with OAuth authentication we recommend these best practices:

  • Create a secret in Secrets Manager with your OAuth credentials.

  • Reference that secret in your CloudFormation template for AWS::Events::Connection using CloudFormation dynamic reference syntax. For more information, see Secrets Manager secrets.

When the Connection resource is created the secret will be passed to EventBridge and stored in the customer account using “Service Linked Secrets,” effectively creating two secrets. This will minimize the cost because the original secret is only accessed when a CloudFormation template is created or updated, not every time an event is sent to the ApiDestination. The secret stored in the customer account by EventBridge is the one used for each event sent to the ApiDestination and AWS is responsible for the fees.

Note

The secret stored in the customer account by EventBridge can’t be updated directly, only when a CloudFormation template is updated.

For examples of CloudFormation templates that use secrets, see Examples.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{
  "Type" : "AWS::Events::ApiDestination",
  "Properties" : {
      "ConnectionArn" : String,
      "Description" : String,
      "HttpMethod" : String,
      "InvocationEndpoint" : String,
      "InvocationRateLimitPerSecond" : Integer,
      "Name" : String
    }
}

YAML

Type: AWS::Events::ApiDestination
Properties:
  ConnectionArn: String
  Description: String
  HttpMethod: String
  InvocationEndpoint: String
  InvocationRateLimitPerSecond: Integer
  Name: String

Properties

ConnectionArn

The ARN of the connection to use for the API destination. The destination endpoint must support the authorization type specified for the connection.

Required: Yes

Type: String

Pattern: ^arn:aws([a-z]|\-)*:events:([a-z]|\d|\-)*:([0-9]{12})?:connection/[\.\-_A-Za-z0-9]+/[\-A-Za-z0-9]+$

Update requires: No interruption

Description

A description for the API destination to create.

Required: No

Type: String

Maximum: 512

Update requires: No interruption

HttpMethod

The method to use for the request to the HTTP invocation endpoint.

Required: Yes

Type: String

Allowed values: GET | HEAD | POST | OPTIONS | PUT | DELETE | PATCH

Update requires: No interruption

InvocationEndpoint

The URL to the HTTP invocation endpoint for the API destination.

Required: Yes

Type: String

Pattern: ^((%[0-9A-Fa-f]{2}|[-()_.!~*';/?:@\x26=+$,A-Za-z0-9])+)([).!';/?:,])?$

Update requires: No interruption

InvocationRateLimitPerSecond

The maximum number of requests per second to send to the HTTP invocation endpoint.

Required: No

Type: Integer

Minimum: 1

Update requires: No interruption

Name

The name for the API destination to create.

Required: No

Type: String

Pattern: [\.\-_A-Za-z0-9]+

Minimum: 1

Maximum: 64

Update requires: Replacement

Return values

Ref

When you pass the logical ID of this resource to the intrinsic Ref function, Ref returns the name of the API destination that was created by the request.

Fn::GetAtt

The Fn::GetAtt intrinsic function returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

For more information about using the Fn::GetAtt intrinsic function, see Fn::GetAtt.

Arn

The ARN of the API destination that was created by the request.

Examples

Create an ApiDestination for PagerDuty

The following example creates an ApiDestination connection to PagerDuty.

JSON

"Parameters": {
   "PagerDutyAPIKeyParam": {
       "Type": "String",
       "Description": "API Key for the PagerDuty Environment",
       "NoEcho": true
},
"Resources": {
   "MyConnection": {
       "Type": "AWS::Events::Connection",
       "Properties": {
           "AuthorizationType": "API_KEY",
           "Description": "Connection to PagerDuty API",
           "AuthParameters": {
               "ApiKeyAuthParameters": {
                   "ApiKeyName": "PagerDuty Authorization",
                   "ApiKeyValue": {
                       "Ref": "PagerDutyAPIKeyParam"
                   }
               }
           }
       }
   },
   "MyApiDestination": {
       "Type": "AWS::Events::ApiDestination",
       "Properties": {
           "ConnectionArn": {
               "Fn::GetAtt": [
                   "MyConnection",
                   "Arn"
               ]
           },
           "Description": "API Destination to send events to PagerDuty",
           "HttpMethod": "POST",
           "InvocationEndpoint": "https://events.pagerduty.com/v2/enqueue"
      }
   },
}

YAML

Parameters:
  PagerDutyAPIKeyParam: 
    Type: String
    Description: API Key for the PagerDuty Environment
    NoEcho: True
        
Resources:
  MyConnection:
    Type: AWS::Events::Connection
    Properties:
      AuthorizationType: API_KEY
      Description: Connection to PagerDuty API
      AuthParameters:
        ApiKeyAuthParameters:
          ApiKeyName: PagerDuty Authorization
          ApiKeyValue: !Ref PagerDutyAPIKeyParam
        
  MyApiDestination:
    Type: AWS::Events::ApiDestination
    Properties:
      ConnectionArn: !GetAtt MyConnection.Arn
      Description: API Destination to send events to PagerDuty
      HttpMethod: POST
      InvocationEndpoint: https://events.pagerduty.com/v2/enqueue

Create an ApiDestination for Slack

The following example creates an ApiDestination connection to Slack.

JSON

"Parameters": {
   "pName": {
       "Type": "String"
    },
   "pEndpoint": {
       "Type": "String"
    },
   "pSecretId": {
       "Type": "String"
    }
 },
"Resources": {
   "SlackRole": {
       "Type": "AWS::IAM::Role",
       "Properties": {
           "AssumeRolePolicyDocument": {
               "Version": "2012-10-17",
               "Statement": [
                {
                   "Effect": "Allow",
                   "Principal": {
                       "Service": [
                           "events.amazonaws.com"
                        ]
                    },
                   "Action": [
                       "sts:AssumeRole"
                    ]
               }
               ]
           },
          "Path": "/service-role/",
          "Policies": [
           {
              "PolicyName": "eventbridge-api-destinations",
              "PolicyDocument": {
                  "Version": "2012-10-17",
                  "Statement": [
                   {
                      "Effect": "Allow",
                      "Action": [
                          "events:InvokeApiDestination"
                       ],
                      "Resource": {
                          "Fn::GetAtt": [
                              "SlackDestination",
                              "Arn"
                           ]
                      }
                  }
                  ]
              }
         }
        ]
      }
    },
   "SlackBus": {
       "Type": "AWS::Events::EventBus",
       "Properties": {
           "Name": {
               "Ref": "pName"
            }
        }
    },
   "SlackConnection": {
       "Type": "AWS::Events::Connection",
       "Properties": {
           "AuthorizationType": "API_KEY",
           "AuthParameters": {
               "ApiKeyAuthParameters": {
                   "ApiKeyName": "Authorization",
                   "ApiKeyValue": {
                       "Fn::Sub": "{{resolve:secretsmanager:arn:aws:secretsmanager:${AWS::Region}:${AWS::AccountId}:secret:${pSecretId}}}"
                    }
                } 
            }
        }
    },
   "SlackDestination": {
       "Type": "AWS::Events::ApiDestination",
       "Properties": {
           "ConnectionArn": {
               "Fn::GetAtt": [
                   "SlackConnection",
                   "Arn"
                ]
            },
           "HttpMethod": "POST",
           "InvocationEndpoint": {
               "Ref": "pEndpoint"
            },
           "InvocationRateLimitPerSecond": 10
        }
    },
   "SlackRule": {
       "Type": "AWS::Events::Rule",
       "Properties": {
           "State": "ENABLED",
           "EventBusName": {
               "Ref": "SlackBus"
            },
           "EventPattern": {
               "detail": {
                   "channel": [
                       "aws-integration-testing"
                    ]
                }
           },
         "Targets": [
          {
              "Id": "slack-destination",
              "Arn": {
                  "Fn::GetAtt": [
                      "SlackDestination",
                      "Arn"
                   ]
              },
             "RoleArn": {
                 "Fn::GetAtt": [
                     "SlackRole",
                     "Arn"
                  ]
              },
            "HttpParameters": {
                "HeaderParameters": {
                    "Content-type": "application/json;charset=utf-8"
                 }
             },
            "InputTransformer": {
                "InputPathsMap": {
                    "channel": "$.detail.channel",
                    "text": "$.detail.text"
                 },
                "InputTemplate": "{\n  \"channel\": <channel>,\n  \"text\": <text>\n}\n"
            }
          }
          ]
        }
    }
 },
"Outputs": {
    "outRole": {
        "Value": {
            "Fn::GetAtt": [
                "SlackRole",
                "Arn"
             ]
         }
     },
    "outBus": {
        "Value": {
            "Fn::GetAtt": [
                "SlackBus",
                "Arn"
             ]
         }
     },
    "outConnection": {
        "Value": {
            "Fn::GetAtt": [
                "SlackConnection",
                "Arn"
             ]
         }
     },
    "outConnectionSecret": {
        "Value": {
            "Fn::GetAtt": [
                "SlackConnection",
                "SecretArn"
             ]
         }
     },
    "outDestination": {
        "Value": {
            "Fn::GetAtt": [
                "SlackDestination",
                "Arn"
             ]
         }
     },
    "outRule": {
        "Value": {
            "Fn::GetAtt": [
                "SlackRule",
                "Arn"
             ]
         }
     }
 }
}

YAML

Parameters:
  pName:
    Type: String
  pEndpoint:
    Type: String
  pSecretId:
    Type: String
    
Resources:
  SlackRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              Service:
                - events.amazonaws.com
            Action:
              - sts:AssumeRole
      Path: '/service-role/'
      Policies:
        - PolicyName: eventbridge-api-destinations
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              - Effect: Allow
                Action:
                  - events:InvokeApiDestination
                Resource: !GetAtt SlackDestination.Arn
  SlackBus:
    Type: AWS::Events::EventBus
      Properties:
        Name: !Ref pName
  SlackConnection:
    Type: AWS::Events::Connection
    Properties:
      AuthorizationType: API_KEY
      AuthParameters:
        ApiKeyAuthParameters:
          ApiKeyName: Authorization
          ApiKeyValue: !Sub '{{resolve:secretsmanager:arn:aws:secretsmanager:${AWS::Region}:${AWS::AccountId}:secret:${pSecretId}}}'
  SlackDestination:
    Type: AWS::Events::ApiDestination
    Properties:
      ConnectionArn: !GetAtt SlackConnection.Arn
      HttpMethod: POST
      InvocationEndpoint: !Ref pEndpoint
      InvocationRateLimitPerSecond: 10
  SlackRule:
    Type: AWS::Events::Rule
    Properties:
      State: ENABLED
      EventBusName: !Ref SlackBus
      EventPattern:
        detail:
          channel: ["aws-integration-testing"]
      Targets:
        - Id: slack-destination
          Arn: !GetAtt SlackDestination.Arn
          RoleArn: !GetAtt SlackRole.Arn
          HttpParameters:
            HeaderParameters:
              Content-type: application/json;charset=utf-8
          InputTransformer:
            InputPathsMap:
              "channel": "$.detail.channel"
              "text": "$.detail.text"
          InputTemplate: |
            {
              "channel": <channel>,
              "text": <text>
            }
Outputs:
  outRole:
    Value: !GetAtt SlackRole.Arn
  outBus:
    Value: !GetAtt SlackBus.Arn
  outConnection:
    Value: !GetAtt SlackConnection.Arn
  outConnectionSecret:
    Value: !GetAtt SlackConnection.SecretArn
  outDestination:
    Value: !GetAtt SlackDestination.Arn
  outRule:
    Value: !GetAtt SlackRule.Arn