How can I pass a connectionId or custom token to VPC Link integration as a header for Amazon API Gateway WebSocket APIs?

Short description

For WebSocket APIs, the connectionId is required to send a callback response from the backend. By default, WebSocket APIs don't pass the ConnectionId to VPC link integration.

Resolution

Using the Amazon API Gateway console and AWS CLI

Note: If you receive errors when running AWS Command Line Interface (AWS CLI) commands, make sure that you’re using the most recent AWS CLI version.

1.    Follow the instructions to create a REST API VPC link and associate it with your Network Load Balancer.

2.    Follow the instructions to set up a WebSocket API integration and create a VPC link private integration endpoint.

3.    To retrieve the integration ID, run the AWS CLI command get-integrations similar to the following:

aws apigatewayv2 get-integrations --api-id <api-id>

4.    Create and save a JSON file named integration.json in the following format:

{
    "ApiId": "<api-id>",
    "IntegrationId": "<integration id retrieved from previous step>",
    "RequestParameters": {
        "integration.request.header.ConnectionId": "context.connectionId", //passing context variable connectionId as ConnectionId header to backend
        "integration.request.header.<header-key>": "route.request.body.<parameter>", // passing a request body parameter as header to backend
        "integration.request.querystring.<querysting-key>": "'static value'" //passing static value as querystring to backend
    }
}

Note: Before proceeding to step 5, remove the comments noted with the forward slashes "//".

5.    To update the integration, run the AWS CLI command update-integration similar to the following:

aws apigatewayv2 update-integration --cli-input-json file://integration.json

6.    To apply these changes, follow the instructions to deploy the REST API.

Using AWS CloudFormation

If you manage Amazon API Gateway using CloudFormation, you can use the AWS::ApiGatewayV2::Integration resource to configure request parameters similar to the following:

Integration:
    Type: AWS::ApiGatewayV2::Integration
    Properties:
      ApiId: !Ref websocket
      ConnectionId: !Ref <VPC-Link-connection-id>
      ConnectionType: VPC_LINK
      IntegrationMethod: <HTTP method to backend >
      IntegrationType: <HTTP_PROXY/HTTP>
      IntegrationUri: "<endpoint-url>"
      RequestParameters:
        "integration.request.header.connectionId": "context.connectionId" #passing context variable 'connectionId' as ConnectionId header to backend
        "integration.request.header.<header-key>": "route.request.body.<parameter>"  #passing a request body parameter as header to backend
        "integration.request.querystring.<querystring-key>": "'static value'" #passing static value as querystring to backend

You can use data mapping to map data from a route request to the VPC link backend integration. For more information, see Map route request data to integration request parameters.

Related information

Setting up WebSocket API integrations