Skip to content

HTTPS Hostnames and SNI

When connecting to a Velosity HTTPS endpoint, use its fully qualified hostname in the URL. Do not connect to an IP address.

Why the hostname matters

Several HTTPS applications can share one public IP address. Before the encrypted connection is established, the client sends the hostname it wants to reach using Server Name Indication (SNI). The proxy uses that hostname to select the matching TLS certificate.

Modern HTTP clients send SNI automatically when the URL contains a hostname, for example:

https://api.example.com/v1/customers

If a client connects by IP address, uses an older TLS library, or overrides TLS settings, it might not send SNI. The proxy intentionally rejects these handshakes. It cannot redirect the client or return an HTTP error because the TLS handshake occurs before the HTTP request.

Integration guidance

  • Configure the integration base URL with the current HTTPS hostname.
  • Do not replace the hostname with an IP address.
  • Keep normal TLS certificate validation enabled.
  • If the integration pins certificates or restricts allowed hostnames, update those settings when the endpoint hostname changes.
  • During a hostname migration, update the integration to the new hostname instead of relying on the legacy endpoint's redirect. If the legacy endpoint must be used temporarily, the client must support HTTPS redirects.

Test SNI from a terminal

These tests use the current production proxy address, 138.197.82.119, while verifying the requested hostname separately. Using the IP ensures the two commands reach the same endpoint.

Correct connection: sends SNI

printf '' | openssl s_client \
  -connect 138.197.82.119:443 \
  -servername api.velosity.one \
  -verify_hostname api.velosity.one \
  -verify_return_error

The TLS handshake should complete and the certificate should validate for api.velosity.one. To display its subject and DNS names:

printf '' | openssl s_client \
  -connect 138.197.82.119:443 \
  -servername api.velosity.one 2>/dev/null |
  openssl x509 -noout -subject -ext subjectAltName

Incorrect connection: explicitly omits SNI

printf '' | openssl s_client \
  -connect 138.197.82.119:443 \
  -noservername \
  -verify_hostname api.velosity.one \
  -verify_return_error

This must fail during the TLS handshake. Typical output includes tlsv1 unrecognized name, SSL alert number 112, and no peer certificate available. That result confirms the proxy did not send another application's certificate as a fallback.

In PowerShell, replace printf '' | with '' |.

For an end-to-end HTTPS request, curl sends SNI when given a hostname:

curl -v --resolve api.velosity.one:443:138.197.82.119 \
  https://api.velosity.one/v1/customers

Without API credentials, an HTTP 401 Unauthorized response is expected after successful TLS certificate validation.

Troubleshooting certificate-name errors

If an integration reports a TLS handshake failure, verify the configured URL and TLS settings first. A client that omits SNI, connects by IP address, or uses a proxy that strips SNI will be rejected before an HTTP request is sent.