[DOCS] Document webhook proxy addon in main README, setup site, and FAQ

[kingpanther13]

Where is the issue?

Setup Wizard, README, FAQ / Troubleshooting

What's wrong or unclear?

The webhook proxy addon (homeassistant-addon-webhook-proxy) has its own DOCS.md with complete setup instructions, but it's not mentioned anywhere in the main documentation — not in the README, the setup website, the FAQ, or the main addon's docs. Users have no way to discover it unless they happen to find it in the HA add-on store.

This matters because the webhook proxy provides a simpler setup path for certain users. Instead of requiring a dedicated tunnel to port 9583 (like Cloudflared), it proxies MCP traffic through HA's main port 8123 — which Nabu Casa and other existing reverse proxies already tunnel. For users who already have Nabu Casa or another reverse proxy pointing at their HA instance, this can be an easier setup than configuring a separate Cloudflare tunnel to port 9583.

In #784, a user with a TLS-configured HAOS installation couldn't connect via the standard direct method. After troubleshooting, they resolved the issue by installing the Nabu Casa webhook addon instead — but only after being pointed to it in the comments. Better documentation would have let them find this option on their own.

How should it be fixed?

Add mentions/references to the webhook proxy addon in:

1. README — List it as an alternative setup option alongside Cloudflared
2. Main addon DOCS.md — Cross-reference the webhook proxy for users who already have Nabu Casa or a reverse proxy pointing at HA's port 8123
3. Setup site (site/src/content/connections/remote.md and/or a new deployment/webhook-proxy.md) — Document it as a deployment option
4. FAQ / Troubleshooting — Add an entry for users with TLS/connection issues pointing them to the webhook proxy as an alternative

A comparison or guidance section would also help users choose the right method:

• Direct to port 9583 (via Cloudflared or port forwarding): No extra hop, simpler architecture — best when you don't already have a reverse proxy or Nabu Casa
• Webhook proxy (via port 8123): Leverages existing Nabu Casa or reverse proxy infrastructure — simpler setup if that's already in place, but adds an extra hop (client → HA → webhook → MCP) and requires an HA restart on first install

It would be worth noting any known limitations or performance differences between the two methods, if any exist. From the issues I've seen, users have gotten both methods working successfully once configured correctly — but a systematic comparison would be valuable.

Additional context

• The webhook proxy addon was added in v7.0.0 (PR feat: add Nabu Casa and other generic remote access via webhook proxy #554) and has its own comprehensive DOCS.md
• [BUG] TLS not supported? #784 — User with TLS issues resolved by switching to webhook addon (discovered only via issue comments)
• The addon auto-detects Nabu Casa and also works with any generic reverse proxy (Cloudflare, DuckDNS, nginx, etc.)

[github-actions]

🔍 Analysis

The user's report is accurate. The Webhook Proxy Add-on (homeassistant-addon-webhook-proxy) was introduced in v7.0.0 (PR #554) to provide a simpler remote access path for Home Assistant users, particularly those with Nabu Casa or existing reverse proxies. However, while it has its own comprehensive DOCS.md, it is completely missing from the main project documentation, setup site, and FAQ.

This omission makes the feature difficult to discover, leading users to struggle with more complex setups (like Cloudflared) when a simpler option exists. My investigation confirms that README.md, homeassistant-addon/DOCS.md, docs/FAQ.md, and the setup site's content files do not mention this add-on.

🛠️ Suggested Steps

1. Create a new deployment guide for the Webhook Proxy in the setup site at site/src/content/deployment/webhook-proxy.md.
2. Update the main README.md to include the Webhook Proxy as an alternative for Home Assistant OS users.
3. Enhance the main add-on documentation (homeassistant-addon/DOCS.md) with a cross-reference to the Webhook Proxy for remote access.
4. Update the Remote Connection guide (site/src/content/connections/remote.md) to list the Webhook Proxy as a deployment option.
5. Add a troubleshooting entry to docs/FAQ.md pointing users to the Webhook Proxy as a solution for TLS or connection issues.

📊 Technical Analysis (for maintainers)

Root Cause

The Webhook Proxy was added to the repository but the documentation updates were limited to its specific subdirectory. The main documentation entry points were not updated to reflect this new deployment path.

Affected Code

• README.md - Main entry point
• homeassistant-addon/DOCS.md - Documentation for the main MCP server add-on
• docs/FAQ.md - Troubleshooting and common questions
• site/src/content/connections/remote.md - Setup site remote connection guide
• site/src/content/deployment/webhook-proxy.md - (New file) Setup site deployment guide

Proposed Fix

I recommend applying the following changes to consolidate the documentation:

1. Create site/src/content/deployment/webhook-proxy.md

---
name: Webhook Proxy Add-on
description: Proxy MCP traffic through Home Assistant's port 8123
icon: home-assistant
forConnections: ['remote']
order: 5
---

## Overview

The **Webhook Proxy** addon (`homeassistant-addon-webhook-proxy`) is a lightweight alternative to Cloudflared for users who already have a reverse proxy (like Nabu Casa, NGINX, or DuckDNS) pointing at their Home Assistant instance.

Instead of requiring a separate tunnel to port 9583, it proxies MCP traffic through Home Assistant's main port 8123 via a secure webhook.

## Why Use This?

- **Simpler Setup**: No new ports to open if you already have remote access to HA.
- **Nabu Casa Support**: Works out-of-the-box with Nabu Casa (Home Assistant Cloud).
- **No Extra Tunnel**: Leverages your existing reverse proxy infrastructure.
- **Security**: MCP traffic is protected by a long, random webhook ID.

## Prerequisites

1. **Home Assistant MCP Server** addon must be installed and running.
2. An active reverse proxy (Nabu Casa, Cloudflare, NGINX, etc.) pointing to your HA instance.

## Installation

1. **Add the repository** to your Home Assistant instance:
   [![Add Repository](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fhomeassistant-ai%2Fha-mcp)

2. **Install "Webhook Proxy for HA MCP"** from the Add-on Store.

3. **Start the addon**. On first run, it will install a small custom integration and ask you to restart Home Assistant.

4. **Restart Home Assistant** (Settings > System > Restart).

5. **Check the addon logs** for your remote URL:

MCP Server URL (remote): https://xxxxx.ui.nabu.casa/api/webhook/mcp_xxxxxxxx

[Full Webhook Proxy documentation →](https://github.com/homeassistant-ai/ha-mcp/blob/master/homeassistant-addon-webhook-proxy/DOCS.md)

2. Update README.md

--- a/README.md
+++ b/README.md
@@ -95,7 +95,7 @@
 
 No token or credential setup needed — the add-on connects to Home Assistant automatically.
 
-[Full add-on documentation →](homeassistant-addon/DOCS.md)
+**Remote access?** Use the [Webhook Proxy add-on](homeassistant-addon-webhook-proxy/DOCS.md) for Nabu Casa/Reverse Proxies. [Full documentation →](homeassistant-addon/DOCS.md)
 
 </details>

3. Update homeassistant-addon/DOCS.md

--- a/homeassistant-addon/DOCS.md
+++ b/homeassistant-addon/DOCS.md
@@ -62,6 +62,18 @@
 
 ### 🌐 Web Clients (Claude.ai, ChatGPT, etc.)
 
+#### Option 1: Webhook Proxy (Recommended for Nabu Casa)
+
+If you already have Nabu Casa or a reverse proxy (NGINX, DuckDNS, etc.) pointing to your Home Assistant instance (port 8123), use the **Webhook Proxy add-on**:
+
+1. Install **"Webhook Proxy for HA MCP"** from the add-on store.
+2. Start the add-on and follow the restart instructions.
+3. Copy the `https://...` URL from the Webhook Proxy logs.
+
+[Webhook Proxy documentation →](https://github.com/homeassistant-ai/ha-mcp/blob/master/homeassistant-addon-webhook-proxy/DOCS.md)
+
+#### Option 2: Cloudflared Tunnel
+
 For secure remote access without port forwarding, use the **Cloudflared add-on**:

4. Update docs/FAQ.md

--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -79,6 +79,14 @@
 
 See [#783](https://github.com/homeassistant-ai/ha-mcp/issues/783) for more details.
 
+### Connection issues with TLS/HTTPS (Home Assistant OS)
+
+If you are using Home Assistant OS and experiencing TLS errors or connection timeouts when trying to connect remotely, the easiest solution is to use the **Webhook Proxy add-on**.
+
+It proxies MCP traffic through Home Assistant's main port (8123), leveraging your existing Nabu Casa or reverse proxy configuration. This bypasses many common networking and certificate issues.
+
+[How to set up the Webhook Proxy →](https://github.com/homeassistant-ai/ha-mcp/blob/master/homeassistant-addon-webhook-proxy/DOCS.md)
+
 ### SSL certificate errors (self-signed certificates)

Related Issues/PRs

• feat: add Nabu Casa and other generic remote access via webhook proxy #554 - PR that added the Webhook Proxy add-on
• [BUG] TLS not supported? #784 - Issue where a user resolved TLS problems by switching to the webhook proxy
• [BUG] Couldn't reach MCP server #783 - Related Cloudflare connection issue

---

🤖 Automated analysis by Issue Bot