APIs enable your applications to make requests, pass data, and use functionality from third-party services. With the launch of API Destinations in Amazon EventBridge, you can now invoke external APIs directly from events within AWS. This makes it easier to integrate your applications with software as a service (SaaS) providers, such as Zendesk or PagerDuty, or send data to any service that exposes a REST API endpoint.

An event occurs when a system state has changed or something happens within your workload. It could be a new object stored in S3, a new sign-in from the console, or a payment processed in your e-commerce application. An event is a JSON structure that contains details about what happened, and there are many events automatically generated by AWS services.

For serverless developers, API Destinations makes it simpler to build microservices that respond to events generated from within your workloads or by AWS services. This integration replaces custom code, helps manage secrets and API keys, and automatically handles queuing and throttling of downstream requests.

By connecting AWS events with external services, you could:

• Issue credit card refunds via Stripe when an approval workflow completes in AWS Step Functions.
• Automatically open GitHub issues in response to build failures in AWS CodeStar.
• Create new product pages in Contentful when data changes in an Amazon DynamoDB table.

In this blog post, I’ll show how you can build an integration with Slack. This results in a message posted to a Slack channel based on an event within your AWS account.

This example uses the AWS Serverless Application Model (AWS SAM) to deploy the solution to your AWS account. You can use the code introduced here to build similar integrations with services like GitHub, Stripe, and Contentful.

Overview

In the example application, you configure API Destinations for Slack and an EventBridge rule to route specific events. The architecture looks like this:

1. AWS services and custom applications generate events. These are represented in JSON.
2. An Amazon EventBridge event bus receives the events.
3. Rules evaluate if the events match specified patterns. The patterns are also represented in JSON and can match attributes on incoming events. Events matching the Slack rule are forwarded to an API Destinations target.
4. The API destination configuration uses a Connection, which contains the authorization secret, and an API. The API contains the target URL, http method, and other configuration information.
5. The external API receives the event. This example uses Slack, but the target URL could be any REST API or webhook.

To get started, you need the AWS CLI and AWS SAM installed. You also need a Slack account but everything shown here can be completed using a free account.

How the API Destinations feature works

EventBridge rules route matching messages to targets, and API Destinations is a type of target. It consists of a Connection, which contains authentication information, and the API configuration. The credentials provided in the connection are stored securely in AWS Secrets Manager. A connection represents a target service and a single connection can be used by multiple APIs and rules.

While you can invoke an external REST API using a Lambda function, API Destinations provides additional management and configuration options that you would otherwise write using custom code. You can configure an Invocation rate per second, which protects the API from sudden traffic spikes and can help smooth out the number of calls in busy systems.

Internally, EventBridge uses a queue to hold requests that exceed this rate. It buffers these messages for up to 24 hours. The maximum timeout for an API destination is 5 seconds and the service retries any calls that exceed this timeout.

Automating AWS Cost Optimization
AWS provides unprecedented value to your business, but using it cost-effectively can be a challenge. In this free, on-demand webinar, you’ll get an overview of AWS cost-optimization tools and strategies.

Testing the API Destinations feature

Webhook.site is a useful debugging tool that echoes any incoming requests, helping to see what has sent in an API call. Before creating the Slack integration, first you deploy an EventBridge rule with an API destination that routes to Webhook.site.

To deploy this solution:

1. Navigate to https://webhook.site/ and copy the unique webhook URL.
2. Clone the code repo:
   git clone https://github.com/aws-samples/serverless-patterns
3. Change directory:
   cd ./eventbridge-api-destinations/1-webhook-site
4. Deploy the AWS SAM template:
   sam deploy --guided
5. When prompted for MyWebhookURL, enter the URL from step 1.

To test the application:

1. Change directory to the main code repository:
   cd ..
2. Send a test event to EventBridge:
   aws events put-events --entries file://testEvent.json
3. The API call arrives in Webhook.site, where you can see the payload and headers:

This sample application passes the entire event payload to the API endpoint. The test event in testEvent.json appears in the Raw content field in Webhook.site.

Understanding the AWS SAM template

The template deploys multiple AWS resources. First, it creates a new event bus:

  MyEventBus:
    Type: AWS::Events::EventBus
    Properties:
      Name: "MyEventBus"

The API Destination consists of a connection and an API. Since this is an open API, the authorization is defined as API_KEY and logged out by Webhook.site:

  MyConnection:
    Type: AWS::Events::Connection
    Properties:
      AuthorizationType: API_KEY
      Description: 'My connection with an API key'
      AuthParameters:
        ApiKeyAuthParameters:
          ApiKeyName: MyWebhook
          ApiKeyValue: MyAPIkey

The API sets the invocation endpoint as the URL provided as a parameter during the deployment. It configures the HTTP method to POST and throttles messages to 10 per second:

MyApiDestination:
    Type: AWS::Events::ApiDestination
    Properties:
      Name: 'MyWebhookTest'
      ConnectionArn: !GetAtt MyConnection.Arn
      InvocationEndpoint: !Ref MyWebhookURL
      HttpMethod: POST
      InvocationRateLimitPerSecond: 10

Finally, the template defines a rule that determines an event pattern and then sets the target to the new API Destination:

  EventRule: 
    Type: AWS::Events::Rule
    Properties: 
      Description: "EventRule"
      State: "ENABLED"
      EventBusName: !Ref MyEventBus
      EventPattern: 
        source:
          - "MyTestApp"
        detail-type:
          - "MyTestMessage"       
      Targets: 
        - Arn: !GetAtt MyApiDestination.Arn
          RoleArn: !GetAtt EventBridgeTargetRole.Arn
          Id: "MyAPIdestination"

The EventBridge service also needs permission to invoke the API destination so the IAM role grants this access.

Get the Cloud Dictionary of Pain
Speaking cloud doesn’t have to be hard. We analyzed millions of responses to ID the top concepts that trip people up. Grab this cloud guide for succinct definitions of some of the most painful cloud terms.

Setting up Slack as an API Destination

First, you must configure bot access to your Slack account. To do this, follow the instructions at Create a bot for your workspace, and note the bot’s token (this code begins with xoxb) and the channel ID. You need both of these values to deploy this solution.

API Destinations supports three different types of authorization: basic username and password, OAuth, and API key. The Slack bot uses the OAuth method, passed in the Authorization header as a bearer token. This token is passed with each API request, enabling Slack to verify the sender.

To deploy the Slack example:

1. From the terminal, change directory:
   cd ../2-slack
2. Deploy the AWS SAM template:
   sam deploy --guided
3. You are prompted for three parameters:
   1. MySlackToken: enter the bot token from the Slack configuration (this begins with xoxb).
   1. MySlackChannel: enter the channel ID from Slack.
   1. MyEventBusName: accept the default value MyEventBus, since this template uses the same event bus deployed in the first example.

To test the Slack integration:

1. Change directory to the main code repository:
   cd ..
2. Send a test event to EventBridge:
   aws events put-events --entries file://testEvent.json
3. The message appears in the Slack channel:

Understanding the AWS SAM template

The Connection resource used in this template configures a token passed in the Authorization header of the API request. It prepends the Slack token with the ‘Bearer’ keyword:

    Type: AWS::Events::Connection
    Properties:
      AuthorizationType: API_KEY
      Description: 'My connection with an API key'
      AuthParameters:
        ApiKeyAuthParameters:
          ApiKeyName: 'Authorization'
          ApiKeyValue: !Sub 'Bearer ${MySlackToken}'

The API configuration uses Slack’s Post Message API and limits the invocation rate to 10 messages per second:

  MyApiDestination:
    Type: AWS::Events::ApiDestination
    Properties:
      Name: 'MySlackNotifier'
      ConnectionArn: !GetAtt MyConnection.Arn
      InvocationEndpoint: 'https://slack.com/api/chat.postMessage'
      HttpMethod: POST
      InvocationRateLimitPerSecond: 10

The rule uses the same event pattern as defined before, filtering for all events with the source MyTestApp and detail-type of MyTestMessage:

  EventRule: 
    Type: AWS::Events::Rule
    Properties: 
      Description: "EventRule"
      State: "ENABLED"
      EventBusName: !Ref MyEventBusName
      EventPattern: 
        source:
          - "MyTestApp"
        detail-type:
          - "MyTestMessage"       
      Targets: 
        - Arn: !GetAtt MyApiDestination.Arn
          RoleArn: !GetAtt EventBridgeTargetRole.Arn
          Id: "MyAPIdestination"
          InputTransformer:
            InputPathsMap:
              text: $.detail.event
            InputTemplate: !Sub >
              {
                "channel": "${MySlackChannel}",
                "text": <text>
              }

In the first example, the entire event payload is passed to the target. However, Slack requires specific JSON attributes so this uses an input transformer to extract these from the payload. The InputPathsMap section defines variables from the payload, while the InputTemplate embeds an AWS SAM parameter and the input path variable. The result is that you can configure a payload to match the specific requirements of the API.

Conclusion

Using API Destinations, you can use EventBridge to invoke third-party APIs without writing any business logic. The service provides configurable throttling and secure key management, while buffering messages for up to 24 hours for messages that exceed this limit.

You can use this integration to extend the capabilities of your workloads by filtering for events generated by AWS services or custom applications. API Destinations builds on existing EventBridge functionality, introducing the Connection and API resources to help configure credentials and define API endpoints.

In these examples, you send messages to a webhook debugging service and Slack. Using the approach shown, you can modify the templates and payload formats to filter for different events and integrate with almost any external REST API endpoint.

To deploy these patterns and others, see the new Serverless Patterns Collection in Serverless Land.

Get the skills you need for a better career.

Master modern tech skills, get certified, and level up your career. Whether you’re starting out or a seasoned pro, you can learn by doing and advance your career in cloud with ACG.