|
| 1 | +# Amazon API Gateway (HTTP) to Amazon Simple Queue Service (SQS) for passing custom http headers as message attributes. |
| 2 | +--- |
| 3 | + |
| 4 | +This pattern enables you to pass custom HTTP headers as message attributes when sending messages from HTTP API Gateway to an SQS queue. The headers can be configured either as static values or dynamically passed from the incoming request headers. In the default configuration, the message attribute name is set as 'MessageAttribute1' which maps to the header name 'header1' in the integration request mapping. You can customize these message attribute, header names and static values, according to your requirements by updating the requestParameters section in the SqsIntegration configuration within your SAM template. You can set the name for API Gateway and the SQS queue. |
| 5 | + |
| 6 | +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 for details. You are responsible for any AWS costs incurred. No warranty is implied in this example. |
| 7 | + |
| 8 | + |
| 9 | +## Requirements |
| 10 | +--- |
| 11 | +1. Create an AWS account 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. |
| 12 | +2. AWS CLI installed and configured |
| 13 | +3. Git Installed |
| 14 | +4. AWS Serverless Application Model (AWS SAM) installed |
| 15 | +5. In the default configuration, the message attribute name is set as 'MessageAttribute1' which maps to the header name 'header1' in the integration request mapping. You can customize these message attribute, header names and static values, according to your requirements by updating the requestParameters section in the SqsIntegration configuration within your SAM template. You can set the name for API Gateway and the SQS queue. |
| 16 | + |
| 17 | + |
| 18 | +## Deployment Instructions: |
| 19 | +--- |
| 20 | +1. Create a new directory, navigate to that directory in a terminal and clone the GitHub repository: |
| 21 | + |
| 22 | +``` |
| 23 | +git clone https://github.com/aws-samples/serverless-patterns |
| 24 | +``` |
| 25 | +2. Change directory to the pattern directory: |
| 26 | + |
| 27 | +``` |
| 28 | +cd serverless-patterns/custom-http-headers-to-sqs-message-attributes-using-http-api-gateway |
| 29 | +``` |
| 30 | +3. From the command line, use AWS SAM to deploy the AWS resources for the pattern as specified in the template.yml file: |
| 31 | + |
| 32 | +``` |
| 33 | +sam deploy --guided |
| 34 | +``` |
| 35 | + |
| 36 | +4. During the prompts enter the values corresponding to each field. The values in the square brackets are the default values, which can be overwritten once you enter the inputs. |
| 37 | + |
| 38 | +``` |
| 39 | + Stack Name: |
| 40 | + AWS Region: |
| 41 | + Parameter ApiGatewayName: |
| 42 | + Parameter QueueName: |
| 43 | + #Shows you resources changes to be deployed and require a 'Y' to initiate deploy |
| 44 | + Confirm changes before deploy [Y/n]: Y |
| 45 | + #SAM needs permission to be able to create roles to connect to the resources in your template |
| 46 | + Allow SAM CLI IAM role creation [Y/n]: |
| 47 | + #Preserves the state of previously provisioned resources when an operation fails |
| 48 | + Disable rollback [y/N]: |
| 49 | + Save arguments to configuration file [Y/n]: |
| 50 | + SAM configuration file [samconfig.toml]: |
| 51 | + SAM configuration environment [default]: |
| 52 | +``` |
| 53 | + |
| 54 | +5. Allow SAM CLI to create IAM roles with the required permissions. |
| 55 | +Once you have run sam deploy --guided mode once and saved arguments to a configuration file (samconfig.toml), you can use sam deploy in future to use these defaults. |
| 56 | + |
| 57 | +6. Note the outputs from the SAM deployment process. These contain the resource names and/or ARNs which are used for later review. |
| 58 | + |
| 59 | + |
| 60 | +## How it works: |
| 61 | +--- |
| 62 | + |
| 63 | +This pattern sets up the following resources: |
| 64 | + |
| 65 | +- A HTTP API Gateway with SQS integration with configurations to map the http headers to message attributes for SQS. The HTTP API will have custom logging enabled and the logs will be sent to the Cloudwatch log group created by the pattern. An SQS queue will be created by the pattern and attached to the API Gateway with default parameters. |
| 66 | + |
| 67 | +- In the output section, the SAM deployment returns ProvidedInputs, HttpApiEndpoint, HttpApiArn, HttpApiId, LogGroupArn, QueueArn, ApiUsageInformation, Required headers, Message body sample, RoleArn and QueueUrl. |
| 68 | + |
| 69 | + |
| 70 | +## Testing: |
| 71 | + |
| 72 | +1. Invoke the API Gateway with required headers and body and see the message being received with the headers as message attributes. |
| 73 | + |
| 74 | +- Replace the values `HTTP-API-ID` with the value from `HttpApiId` key from the `sam deploy` command. Replace `region` with the region you have the stack deployed to. |
| 75 | + |
| 76 | +CLI: |
| 77 | +``` |
| 78 | +curl --location 'https://<HTTP-API-ID>.execute-api.<region>.amazonaws.com/sqs' \ |
| 79 | + --header 'header1: value for header1 which will go as MessageAttribute1' \ |
| 80 | + --header 'header2: value for header2 which will go as MessageAttribute2' \ |
| 81 | + --header 'Content-Type: application/json' \ |
| 82 | + --data '{ |
| 83 | + "MessageBody": "Payload from client via HTTP API Gateway" |
| 84 | + }' |
| 85 | +``` |
| 86 | + |
| 87 | +2. Use Case requirements: |
| 88 | + |
| 89 | +Required Headers: |
| 90 | + |
| 91 | +- The following headers and their corresponding values are expected to passed along with the request when using this template |
| 92 | + --> `header1` (key and value) is required for `MessageAttribute1` |
| 93 | + --> `header2`(key and value) is required for `MessageAttribute2` |
| 94 | + --> `static_header3` is the static value being configured for `MessageAttribute3` header. |
| 95 | + |
| 96 | +Since is it configured this header is not mandatory when sending the request. |
| 97 | + |
| 98 | + |
| 99 | +Request Body Format: |
| 100 | + |
| 101 | +{ |
| 102 | + "MessageBody": "Your message here" |
| 103 | +} |
| 104 | + |
| 105 | + |
| 106 | +Message received in SQS will have the following attributes. |
| 107 | + |
| 108 | +Attributes (3) |
| 109 | +--> Name: MessageAttribute1 | Type: String | Value: value for header1 which will go as MessageAttribute1 |
| 110 | +--> Name: MessageAttribute2 | Type: String | Value: value for header2 which will go as MessageAttribute2 |
| 111 | +--> Name: MessageAttribute3 | Type: String | Value: static_header3 |
| 112 | + |
| 113 | + |
| 114 | +## Cleanup |
| 115 | +--- |
| 116 | + |
| 117 | +- Delete the stack: |
| 118 | + |
| 119 | + ``` |
| 120 | + sam delete |
| 121 | + ``` |
| 122 | + |
| 123 | +- Confirm the stack has been deleted |
| 124 | + |
| 125 | + ``` |
| 126 | + aws cloudformation list-stacks --query "StackSummaries[?contains(StackName,'STACK_NAME')].StackStatus" |
| 127 | + ``` |
| 128 | +
|
| 129 | +--- |
| 130 | +Copyright 2026 Amazon.com, Inc. or its affiliates. All Rights Reserved. |
| 131 | +
|
| 132 | +SPDX-License-Identifier: MIT-0 |
0 commit comments