How do I pass a connectionId or custom token to VPC link integration as a header for API Gateway WebSocket APIs?

Short description

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

To pass a connectionID or custom token, use the API Gateway console and the AWS Command Line Interface (AWS CLI), or use AWS CloudFormation.

Resolution

Note: If you receive errors when you run AWS CLI commands, then see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.

Use the API Gateway console and the AWS CLI

Complete the following steps:

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:

   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",
       "integration.request.header.<header-key>": "route.request.body.<parameter>",
       "integration.request.querystring.<querysting-key>": "'static value'"
     }
   }

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 WebSocket API.

Use CloudFormation

If you use CloudFormation to manage API Gateway, then 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

Integrations for WebSocket API in API Gateway