🧩 Braze SDK Custom Endpoint via Reverse Proxy

📘 Context

Our goal was to configure the Braze SDK to use a custom endpoint (sdk.example.com) instead of the default Braze regional endpoint (sdk.iad-05.braze.com).
This setup was needed to simplify network configurations, overcome corporate firewall restrictions, and provide internal visibility and control over outbound SDK traffic.

---

⚙️ Implementation Summary

Architecture Overview

We implemented a reverse proxy layer that securely forwards Braze SDK traffic to the real Braze endpoint.

[Braze SDK] → sdk.example.com → [Reverse Proxy] → sdk.iad-05.braze.com

Key Steps

1. Custom Domain Setup
   • Created a DNS record:
     sdk.example.com → points to our proxy (e.g. Cloudflare, NGINX, or API Gateway).
2. TLS Configuration
   • Configured a valid SSL certificate for sdk.example.com on the proxy (e.g., via Let’s Encrypt or Cloudflare-managed certificate).
   • The proxy terminates TLS from the SDK, then establishes a new HTTPS connection to sdk.iad-05.braze.com.
3. Proxy Forwarding Rules
   • All incoming requests to / on sdk.example.com are forwarded to the real Braze endpoint.
   • Headers and body are passed transparently (Host, Content-Type, etc.).
   • Keep-alive connections are enabled for performance.
4. SDK Configuration
   • The Braze SDK endpoint was set to sdk.example.com in app initialization.

---

🔒 Security & Compliance Notes

• TLS Handshake Issue Resolved:
  By terminating TLS at the proxy (with a valid sdk.example.com certificate), we avoided the hostname mismatch problem that occurs with raw CNAMEs.
• No Payload Modification:
  The proxy is configured as a transparent forwarder. It does not modify requests or responses.
• Network Control:
  This setup allows monitoring and controlling outbound traffic without breaking Braze SDK integrity.

---

✅ Benefits

Benefit	Description
🔐 TLS Validity	Custom SSL certificate for internal domain
🧭 Network Control	Easier firewall rules and observability
⚙️ Compatibility	SDK operates normally, unaware of the proxy
📊 Monitoring	Possible to log, inspect, and audit traffic safely

---

⚠️ Considerations

• Support Disclaimer:
  This setup is not officially supported by Braze, as custom SDK endpoints were deprecated in 2019.
  However, it is technically safe as long as requests are transparently forwarded without modification.

• Maintain Low Latency:
  The proxy must be deployed in a region close to the app users or Braze cluster to minimize latency.

• Keep Proxy Stateless:
  Avoid caching, compression, or persistent state. The proxy should behave like a secure network tunnel.

---

🧠 Takeaway

A simple CNAME wouldn’t work because of TLS certificate mismatches, but implementing a reverse proxy with SSL termination and transparent forwarding successfully allows us to use a custom Braze SDK endpoint while keeping all SDK functions intact.

---

🧩 Example (NGINX Snippet)

server {
  listen 443 ssl;
  server_name sdk.example.com;

  ssl_certificate /etc/ssl/certs/sdk.example.com.crt;
  ssl_certificate_key /etc/ssl/private/sdk.example.com.key;

  location / {
    proxy_pass https://sdk.iad-05.braze.com;
    proxy_set_header Host sdk.iad-05.braze.com;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_ssl_server_name on;
    proxy_ssl_name sdk.iad-05.braze.com;
  }
}