Multi-region disaster recovery for Amazon API Gateway WebSocket APIs

AWS published an active-passive design for Amazon API Gateway WebSocket APIs that reconnects clients and restores session state during a Regional failover, according to AWS Architecture Blog's report. Identical stacks run in a primary Region and a secondary Region behind one custom domain. Amazon Route 53 DNS failover stays on the primary until it is unhealthy, then shifts DNS to the secondary. Amazon DynamoDB Global Tables replicate the shared state, and a traffic-independent canary detects the failure.

This piece is for teams that run persistent, bidirectional WebSocket apps on AWS: financial trading applications streaming live market data, collaborative editing tools where several people share one document, gaming leaderboards updating in real time, and IoT dashboards monitoring thousands of devices. It follows the failover path in Figure 1, the canary and heartbeat that detect an unhealthy Region, how session rows are keyed, the auction demo, and Amazon Aurora Global Database for relational state.

Multi-region disaster recovery for Amazon API: what actually changed

Each WebSocket is persistent and bound to one AWS Region, so a Regional failure severs every active connection. A live auction or collaborative editor loses session context. State is stored apart from the connection and restored when the client reconnects. Identical API Gateway stacks in the primary and secondary share DynamoDB Global Tables, so the secondary stays ready. One custom domain fronts both. Route 53 failover routing returns the primary endpoint until it is unhealthy, then the secondary. Clients resume with no configuration change.

A user connects a WebSocket to the domain. Route 53 returns the primary endpoint. API Gateway invokes AWS Lambda for each connection event and message. Lambda reads and writes DynamoDB, and clients get updates. Global Tables replicate state to the secondary asynchronously. Amazon EventBridge runs a canary Lambda every minute to open a WebSocket, send a heartbeat, and publish an Amazon CloudWatch metric. An alarm fires on consecutive failures or if the canary stops publishing. The health check marks the primary unhealthy, and clients read the local DynamoDB replica.

Multi-region disaster recovery for Amazon API: how it works

The client and the canary use an application-level heartbeat, the WebSocket check RFC 6455 describes. A lightweight message must be acknowledged, and a missing or invalid response means the connection is broken. The client reconnects, and the canary drives the Route 53 health check. Samples use react-use-websocket, a React library with reconnection and heartbeat support. Other libraries or languages can match it. The JSON action is heartbeat, the return message is pong, timeout 35000 closes the socket after 35 seconds of silence, and interval 30000 sends a heartbeat every 30 seconds.

A Lambda canary in the primary Region probes the endpoint every minute by opening a WebSocket, sending a heartbeat, and confirming a valid response. It publishes CloudWatch metric App/WebSocketHealth, dimension ApiId, as 1 when healthy and 0 when unhealthy. TreatMissingData is set to breaching, so failures and missing data are both unhealthy. After two consecutive unhealthy datapoints the alarm fires. The Route 53 health check sets InsufficientDataHealthStatus to Unhealthy and marks the primary down. Route 53 then resolves the custom domain to the secondary Region.

Multi-region disaster recovery for Amazon API: why it matters now

Real-time apps need a two-way socket, so a Regional outage ends every session at once. Session data tied to user identity must already be in the Region that accepts the reconnect. DynamoDB Global Tables replicate it asynchronously, typically within a second. Writes immediately before the failure may not reach the secondary. For most applications that window is small enough to be acceptable. The demo client sends a getState message and reads the latest state from the secondary Region's DynamoDB replica.

WebSocket APIs authenticate on the $connect route, so the secondary Region re-authenticates through a Lambda authorizer deployed in both Regions. The user comes from the validated token, such as the sub claim, and state is keyed by user ID. The connection ID changes on every reconnect. Session models can adapt this key. Amazon Aurora Global Database provides sub-second replication across Regions for relational state. Promoting its read replica to primary typically adds 1-2 minutes, and a CloudWatch alarm action can automate the promotion.

Multi-region disaster recovery for Amazon API: who is affected

The demo is a real-time auction where multiple users bid on one item at the same time. Each bid updates a shared counter through WebSocket messages, and connected clients see the current bid in real time. The application shows which AWS Region is serving responses, so failover is visible during testing. It represents chat applications, collaborative editors, live dashboards, and multiplayer games that share mutable state over WebSockets. Single-Region operators lose every connection and the session context in a Regional failure.

An AWS account needs permission to create Amazon API Gateway, AWS Lambda, Amazon DynamoDB, Amazon CloudWatch, and Route 53 resources. The domain needs a hosted zone in Route 53 and AWS Certificate Manager certificates in both the primary and secondary Regions. AWS Command Line Interface (AWS CLI) v2 must be configured, and the client application needs Node.js 18.x or later. The GitHub repository holds source code, deployment instructions, and CloudFormation templates for the WebSocket APIs, the canary health probe, and a React client with the reconnection logic.

Multi-region disaster recovery for Amazon API: what to watch

Global Tables replicate asynchronously, typically within a second, so a write just before failure can miss the secondary. Aurora Global Database replication is also sub-second, yet promoting the read replica to primary typically adds 1-2 minutes. EventBridge runs the canary every minute in the primary Region. App/WebSocketHealth with dimension ApiId is 1 or 0. TreatMissingData set to breaching counts missing canary data as unhealthy. Two consecutive unhealthy datapoints fire the alarm, and InsufficientDataHealthStatus set to Unhealthy lets Route 53 shift DNS to the secondary.

The sample heartbeat sends action heartbeat, expects pong, repeats every 30000 milliseconds, and closes the socket if no message arrives within 35000 milliseconds. That close makes react-use-websocket reconnect. Other clients need the same 30-second interval and 35-second timeout. After DNS moves, the $connect route runs in the secondary Region, so the Lambda authorizer must exist in both Regions. The client sends getState. Rows use the user ID from the token, such as the sub claim, because the connection ID is new on every reconnect.