From 116cc220190972523fb3bfa33dc9c47dea5f561f Mon Sep 17 00:00:00 2001
From: -LAN- <laipz8200@outlook.com>
Date: Wed, 18 Mar 2026 14:28:33 +0800
Subject: [PATCH] fix: clarify webhook debug endpoint behavior (#33597)

---
 api/controllers/trigger/webhook.py            | 32 +++++++++++++++++--
 .../controllers/trigger/test_webhook.py       | 28 +++++++++++++++-
 2 files changed, 57 insertions(+), 3 deletions(-)

diff --git a/api/controllers/trigger/webhook.py b/api/controllers/trigger/webhook.py
index 22b24271c6..eb579da5d4 100644
--- a/api/controllers/trigger/webhook.py
+++ b/api/controllers/trigger/webhook.py
@@ -70,7 +70,14 @@ def handle_webhook(webhook_id: str):
 
 @bp.route("/webhook-debug/<string:webhook_id>", methods=["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"])
 def handle_webhook_debug(webhook_id: str):
-    """Handle webhook debug calls without triggering production workflow execution."""
+    """Handle webhook debug calls without triggering production workflow execution.
+
+    The debug webhook endpoint is only for draft inspection flows. It never enqueues
+    Celery work for the published workflow; instead it dispatches an in-memory debug
+    event to an active Variable Inspector listener. Returning a clear error when no
+    listener is registered prevents a misleading 200 response for requests that are
+    effectively dropped.
+    """
     try:
         webhook_trigger, _, node_config, webhook_data, error = _prepare_webhook_execution(webhook_id, is_debug=True)
         if error:
@@ -94,11 +101,32 @@ def handle_webhook_debug(webhook_id: str):
                 "method": webhook_data.get("method"),
             },
         )
-        TriggerDebugEventBus.dispatch(
+        dispatch_count = TriggerDebugEventBus.dispatch(
             tenant_id=webhook_trigger.tenant_id,
             event=event,
             pool_key=pool_key,
         )
+        if dispatch_count == 0:
+            logger.warning(
+                "Webhook debug request dropped without an active listener for webhook %s (tenant=%s, app=%s, node=%s)",
+                webhook_trigger.webhook_id,
+                webhook_trigger.tenant_id,
+                webhook_trigger.app_id,
+                webhook_trigger.node_id,
+            )
+            return (
+                jsonify(
+                    {
+                        "error": "No active debug listener",
+                        "message": (
+                            "The webhook debug URL only works while the Variable Inspector is listening. "
+                            "Use the published webhook URL to execute the workflow in Celery."
+                        ),
+                        "execution_url": webhook_trigger.webhook_url,
+                    }
+                ),
+                409,
+            )
         response_data, status_code = WebhookService.generate_webhook_response(node_config)
         return jsonify(response_data), status_code
 
diff --git a/api/tests/unit_tests/controllers/trigger/test_webhook.py b/api/tests/unit_tests/controllers/trigger/test_webhook.py
index d633365f2b..91c793d292 100644
--- a/api/tests/unit_tests/controllers/trigger/test_webhook.py
+++ b/api/tests/unit_tests/controllers/trigger/test_webhook.py
@@ -23,6 +23,7 @@ def mock_jsonify():
 
 class DummyWebhookTrigger:
     webhook_id = "wh-1"
+    webhook_url = "http://localhost:5001/triggers/webhook/wh-1"
     tenant_id = "tenant-1"
     app_id = "app-1"
     node_id = "node-1"
@@ -104,7 +105,32 @@ class TestHandleWebhookDebug:
     @patch.object(module.WebhookService, "get_webhook_trigger_and_workflow")
     @patch.object(module.WebhookService, "extract_and_validate_webhook_data")
     @patch.object(module.WebhookService, "build_workflow_inputs", return_value={"x": 1})
-    @patch.object(module.TriggerDebugEventBus, "dispatch")
+    @patch.object(module.TriggerDebugEventBus, "dispatch", return_value=0)
+    def test_debug_requires_active_listener(
+        self,
+        mock_dispatch,
+        mock_build_inputs,
+        mock_extract,
+        mock_get,
+    ):
+        mock_get.return_value = (DummyWebhookTrigger(), None, "node_config")
+        mock_extract.return_value = {"method": "POST"}
+
+        response, status = module.handle_webhook_debug("wh-1")
+
+        assert status == 409
+        assert response["error"] == "No active debug listener"
+        assert response["message"] == (
+            "The webhook debug URL only works while the Variable Inspector is listening. "
+            "Use the published webhook URL to execute the workflow in Celery."
+        )
+        assert response["execution_url"] == DummyWebhookTrigger.webhook_url
+        mock_dispatch.assert_called_once()
+
+    @patch.object(module.WebhookService, "get_webhook_trigger_and_workflow")
+    @patch.object(module.WebhookService, "extract_and_validate_webhook_data")
+    @patch.object(module.WebhookService, "build_workflow_inputs", return_value={"x": 1})
+    @patch.object(module.TriggerDebugEventBus, "dispatch", return_value=1)
     @patch.object(module.WebhookService, "generate_webhook_response")
     def test_debug_success(
         self,