Use @connections commands in your backend service - Amazon API Gateway

Use @connections commands in your backend service

Your backend service can use the following WebSocket connection HTTP requests to send a callback message to a connected client, get connection information, or disconnect the client.


These requests use IAM authorization, so you must sign them with Signature Version 4 (SigV4). To do this, you can use the API Gateway Management API. For more information, see ApiGatewayManagementApi.

In the following command, you need to replace {api-id} with the actual API ID, which is displayed in the API Gateway console or returned by the AWS CLI create-api command. In addition, if your API is in a Region other than us-east-1, you need to substitute the correct Region.

To send a callback message to the client, use:

POST https://{api-id}{stage}/@connections/{connection_id}

You can test this request by using Postman or by calling awscurl as in the following example:

awscurl --service execute-api -X POST -d "hello world" https://{prefix}{stage}/@connections/{connection_id}

You need to URL-encode the command as in the following example:

awscurl --service execute-api -X POST -d "hello world"

To get the latest connection status of the client, use:

GET https://{api-id}{stage}/@connections/{connection_id}

To disconnect the client, use:

DELETE https://{api-id}{stage}/@connections/{connection_id}

You can dynamically build a callback URL by using the $context variables in your integration. For example, if you use Lambda proxy integration with a Node.js Lambda function, you can build the URL as follows:

exports.handler = function(event, context, callback) { var domain = event.requestContext.domainName; var stage = event.requestContext.stage; var connectionId = event.requestContext.connectionId; var callbackUrl = util.format(util.format('https://%s/%s/@connections/%s', domain, stage, connectionId)); // Do a SigV4 and then make the call }