|
| 1 | +# Sending events from Amazon EventBridge to AWS AppSync Events |
| 2 | + |
| 3 | +This pattern demonstrates how you can send events from EventBridge to an AppSync Event API. This will allow you to consume events in real-time over WebSockets. This stack will deploy the following resources: |
| 4 | +- **Amazon AppSync Events API**: Used as the destination which EventBridge will send events to. |
| 5 | +- **API Key**: To allow interactions with the above API. |
| 6 | +- **EventBridge Event bus**: Use this event bus to send messages to for testing. |
| 7 | +- **EventBridge Rule**: Catches messages matching a pattern specified in the template. |
| 8 | +- **EventBridge API Destination**: HTTP invocation endpoint configured as a target for events. In this case, it's our pre-existing AppSync Event API HTTP endpoint passed in as a parameter. |
| 9 | +- **EventBridge Connection**: Defines the authorization type and credentials to use for authorization with an API destination. In this case, we use the pre-existing API key passed in as a parameter. |
| 10 | +- **SQS Queue**: Stores messages that couldn't be delivered to the API destination successfully) |
| 11 | +- **SQS Queue Policy**: The resource policy of the SQS queue, allowing EventBridge to put messages into the DLQ. |
| 12 | +- **IAM Role**: IAM role which eventbridge assumes, the policy below is attached to it. |
| 13 | +- **IAM Policy**: Defines permissions to allow EventBridge to invoke the API destination. |
| 14 | + |
| 15 | +Important: this application uses various AWS services and there are costs associated with these services after the Free Tier usage - please see the [AWS Pricing page](https://aws.amazon.com/pricing/) for details. You are responsible for any AWS costs incurred. No warranty is implied in this example. |
| 16 | + |
| 17 | +## Requirements |
| 18 | + |
| 19 | +* [Create an AWS account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html) if you do not already have one and log in. The IAM user that you use must have sufficient permissions to make necessary AWS service calls and manage AWS resources. |
| 20 | +* [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) installed and configured |
| 21 | +* [Git Installed](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) |
| 22 | +* [AWS Serverless Application Model](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html) (AWS SAM) installed |
| 23 | + |
| 24 | +## Deployment Instructions |
| 25 | + |
| 26 | +1. Create a new directory, navigate to that directory in a terminal and clone the GitHub repository: |
| 27 | + ``` |
| 28 | + git clone https://github.com/aws-samples/serverless-patterns |
| 29 | + ``` |
| 30 | +1. Change directory to the pattern directory: |
| 31 | + ``` |
| 32 | + cd eventbridge-to-appsync-events |
| 33 | + ``` |
| 34 | +1. From the command line, use AWS SAM to deploy the AWS resources for the pattern as specified in the template.yml file: |
| 35 | + ``` |
| 36 | + sam deploy --guided --capabilities CAPABILITY_NAMED_IAM |
| 37 | + ``` |
| 38 | +1. During the prompts: |
| 39 | + * Enter a stack name |
| 40 | + * Allow SAM CLI to create IAM roles with the required permissions. |
| 41 | + * Keep default values to the rest of the parameters. |
| 42 | +
|
| 43 | + Once you have run `sam deploy --guided` once and saved arguments to a configuration file (samconfig.toml), you can use `sam deploy` in future to use these defaults. |
| 44 | +
|
| 45 | +1. Note the `EventBusName` and `EventApiName` values from the SAM deployment process. You will use this in the testing process in the Console. |
| 46 | +
|
| 47 | +## How it works |
| 48 | +
|
| 49 | +A new EventBridge event bus is created with a rule to catch events in your account which match a specified detail-type. These events are then sent to an API Destination which is an AppSync Event API. If there are errors delivering these events to your Events API, they will be delivered to a dead-letter queue (DLQ) where you can inspect what went wrong. |
| 50 | +
|
| 51 | +### How to change what is sent to your Events API |
| 52 | +
|
| 53 | +* [This link ](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-transform-target-input.html) describes how you can change the mapping templates in the EventBridge rules. You will see these in the CloudFormation Template under `InputTemplate` and `InputTransformer`. |
| 54 | +
|
| 55 | +## Testing |
| 56 | +
|
| 57 | +### Set up your Event API to listen to events |
| 58 | +- Navigate to the AppSync Console and find the Event API created by the stack. You can find the name in the outputs with the key `EventApiName`. Click on it. |
| 59 | +- Click the Pub/Sub Editor editor tab. |
| 60 | +- Scroll down to the Subscribe section and click on "connect". |
| 61 | +- For channel, leave the `default` parameter as it is. Replace `/*` with `/serverless-patterns`. |
| 62 | +- Click on Subscribe. You should see a `subscribe_success` message. |
| 63 | +
|
| 64 | +### Publish test events to EventBridge |
| 65 | +
|
| 66 | +- Open the Amazon EventBridge Console in a new tab. |
| 67 | +- Click "Event buses" on the left menu. |
| 68 | +- On the top right, click "send events". |
| 69 | +- For the event bus dropdown, select the newly created event bus. You can find the name in the outputs with the key `EventBusName`. For "event source" enter anything (e.g `example.serverlesspatterns`) and for "detail type" enter `serverless-patterns`. |
| 70 | +- Enter the following payload: `{"message":"hello from test"}`. |
| 71 | +- Click "Send". |
| 72 | +- Navigate back to your Events API tab, you should see a new message arrived in the subscription area as follows: |
| 73 | +``` |
| 74 | +{ |
| 75 | + "detailType": "serverless-patterns", |
| 76 | + "region": "{{your-region}}", |
| 77 | + "message": "hello from test" |
| 78 | +} |
| 79 | +``` |
| 80 | +
|
| 81 | +### Troubleshooting |
| 82 | +
|
| 83 | +**Check the Event Bus Name**: Ensure you are sending test messages to the correct event bus (name is in the outputs of the stack) with "detail type" of `serverless-patterns`. This example won't work on the default event bus. |
| 84 | +
|
| 85 | +**Events not arriving to Event API Console**: Go to the SQS console, find the SQS queue created by this stack (which is your DLQ) and poll for messages. Any errors should be shown in the attributes tab of the messages. |
| 86 | +
|
| 87 | +**No messages in DLQ**: Double check that you have subscribed to the correct namespace/channel `default/serverless-patterns` in the Event API Console. Triple check you are sending messages to the correct event bus. |
| 88 | +
|
| 89 | +## Cleanup |
| 90 | + |
| 91 | +1. Delete the stack |
| 92 | + ```bash |
| 93 | + sam delete |
| 94 | + ``` |
| 95 | +
|
| 96 | +---- |
| 97 | +Copyright 2025 Amazon.com, Inc. or its affiliates. All Rights Reserved. |
| 98 | +
|
| 99 | +SPDX-License-Identifier: MIT-0 |
0 commit comments