Summary:

The RingCentral Cloud Relay is designed to act as a relay between two systems that cannot natively exchange information with one another.

Cloud Relay will 'translate' (or just relay) the messages from the source system and send them to the relay-target/destination.

Use Cases:

  • #1 - Customer/3rd party HTTP endpoint requires SOAP messaging; Cloud Relay can be used to translate REST messages from RingCentral to SOAP.
  • #2 - Customer/3rd party HTTP endpoint requires a site-to-site VPN to connect to them.
  • #3 - Customer/3rd party HTTP endpoint requires certificate-based authentication; Cloud Relay can provide the certificate in each request from RingCentral to the customer/3rd party system.
  • #4 - Customer/3rd party HTTP endpoint requires IP whitelisting/allowing only a small number (2-4) of public IP addresses to connect to their public API, rather than all of the RingCentral supernets.

Cloud Relay AWS API Endpoints:

  • GET /ping: returns pong if Cloud Relay-specific credentials are set correctly via HTTP headers. Use to verify x-api-key and x-api-secret values, and connectivity to the Cloud Relay API Gateway(s).
  • POST /apisecret: used to rotate the value of x-api-secret as required. New value should be sent in the body, using secretKey as the key, and the new secret as the value.
  • ANY /{proxy}: replace {proxy} with the remote API URL that should receive the requests.

Required HTTP Headers included in each Cloud Relay:

  • x-api-key: static value, per AWS API Gateway, used to control which requests are accepted.
  • x-api-secret: can be rotated programmatically via the /apisecret endpoint. This can help satisfy certain security and compliance regulations.
  • relay-target: value contains the URL of the remote server that Cloud Relay will relay the request to.
     - If your API endpoint has additional resources at the end of the URL, set relay-target as the base URL, and append the resource string to the end of the request URL.
     - EG: if your API endpoint is: https://google.com/api/users/tyler
     - relay-target = https://google.com
     - Request URL = https://{{uswest_apigw}}/api/users/tyler

Other Notes:

  • Generally, we will not have internal DNS resolution to the remote/customer environment, so be sure to collect and use the internal IP addresses of any customer API endpoints.

To Do:

  • Add info on Lambda timeouts, max values, etc.
  • Add info on parsing Grafana logs

Example diagram using Cloud Relay to connect to customer's on-prem SymXchange system:

Example Cloud Relay diagram