Skip to content

Self-improving AI Employees for everyone

fix(webhook): refuse oversized webhook bodies and stop queueing events

trohitg1ebfd5d9dae0
diff --git a/.env.template b/.env.template
index f198c443..40606686 100644
--- a/.env.template
+++ b/.env.template
@@ -216,6 +216,13 @@ TEMPORAL_WORKER_RESTART_BACKOFF_MAX_SECONDS=30.0
# the legacy event_waiter path -- see docs-internal/event_framework.md.
EVENT_FRAMEWORK_ENABLED=true
+# Largest webhook request body accepted, in bytes (/webhook/... routes and
+# Discord interactions); a larger one is refused with 413 before it reaches
+# a workflow. A body rides into the workflow's input, which Temporal caps
+# at 2 MB, and the trigger path copies it several times, so one oversized
+# webhook could otherwise wedge a deployment.
+WEBHOOK_MAX_BODY_BYTES=262144
+
# Memory compaction. ``true`` (default) auto-compacts an agent's
# conversation when it nears the model's context-window threshold (see
# COMPACTION_RATIO). Per-session overrides via the UI.
diff --git a/CLAUDE.md b/CLAUDE.md
index 7b5ac913..9b4ac4c6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -701,8 +701,9 @@ Node groups (palette categories) are registered in [`server/nodes/groups.py`](./
#### Webhook Router (`server/routers/webhook.py`)
- `ANY /webhook/{path}` - Dynamic webhook endpoint for incoming HTTP requests (GET, POST, PUT, DELETE, PATCH)
-- Dispatches `webhook_received` event via `broadcaster.send_custom_event()` to trigger waiting webhookTrigger nodes
-- Returns immediate 200 OK response (responseNode mode planned for future)
+- A path a plugin registered with `register_webhook_source` (Stripe, Dodo Payments, WhatsApp Business) goes to that `WebhookSource`; any other path reaches webhookTrigger nodes through `nodes/trigger/webhook_trigger/_events.broadcast_webhook_received` (`dispatch.emit`)
+- A body larger than `WEBHOOK_MAX_BODY_BYTES` (default in `.env.template`) gets 413 before anything is dispatched (`services/events/webhook.read_body_capped`, also used by Discord interactions), because the body rides into a workflow's input
+- Returns 200 OK once dispatched (responseNode mode planned for future)
- `GET /webhook/` - Webhook endpoint info and usage documentation
#### Workspace Router (`server/routers/workspace.py`)
diff --git a/docs-internal/event_framework.md b/docs-internal/event_framework.md
index 983de4d6..a5253d78 100644
--- a/docs-internal/event_framework.md
+++ b/docs-internal/event_framework.md
@@ -92,6 +92,17 @@ services/events/dispatch.py:emit(event: WorkflowEvent)
(skipped with emit(..., broadcast=False))
```
+**Webhook bodies are capped at the edge.** Every webhook body is read through
+`services/events/webhook.read_body_capped`: the generic `/webhook/{path}`
+route, `WebhookSource.handle` (Stripe, Dodo Payments, WhatsApp Business) and
+Discord interactions. A body larger than `WEBHOOK_MAX_BODY_BYTES` (default in
+`.env.template`) gets 413 before anything is dispatched, because the body
+rides into a workflow's input, which Temporal caps at 2 MB, and the trigger
+path copies it several times (RFC-0004 C1). The declared `Content-Length`
+refuses an honest oversized request before it is read; the running total of
+what actually arrives is the limit. `WebhookSource.handle` no longer puts
+each event on the source's queue, which nothing read.
+
**Private payloads skip the broadcast.** The broadcast reaches every
connected socket. An event whose payload is one owner's content passes
`broadcast=False` and reaches only the signalled workflows: chat does, since
diff --git a/server/nodes/discord/_router.py b/server/nodes/discord/_router.py
index 7db92faf..c1bb80c0 100644
--- a/server/nodes/discord/_router.py
+++ b/server/nodes/discord/_router.py
@@ -30,6 +30,7 @@ from fastapi.responses import JSONResponse
from core.logging import get_logger
from services.events.oauth_lifecycle import make_oauth_callback_router
+from services.events.webhook import read_body_capped
from . import _interactions
from ._accounts import DEFAULT_ACCOUNT, PUBLIC_KEY_KEY, storage_scope
@@ -76,7 +77,7 @@ async def _handle_interaction(request: Request, account_id: str) -> Response:
# The signature covers the exact bytes Discord sent. Re-serialising the
# parsed JSON would change key order or separators and break verification
# for authentic requests, so the body is read raw and parsed afterwards.
- body = await request.body()
+ body = await read_body_capped(request)
public_key = await _public_key(account_id)
if not public_key:
diff --git a/server/routers/webhook.py b/server/routers/webhook.py
index 45f360a5..7991ca41 100644
--- a/server/routers/webhook.py
+++ b/server/routers/webhook.py
@@ -3,13 +3,16 @@
Two dispatch paths:
1. **Plugin-owned WebhookSource** (Wave 12 framework). Plugins register
- a :class:`services.events.WebhookSource` for their path; the router
- verifies the signature, shapes a :class:`WorkflowEvent`, and queues
- it onto the source. The source's owning plugin pulls events via
- ``source.emit()`` and dispatches into ``event_waiter``.
-2. **Legacy generic webhook** (pre-framework). Falls through to
- ``broadcaster.send_custom_event("webhook_received", …)`` so existing
- ``webhookTrigger`` nodes keep working untouched.
+ a :class:`services.events.WebhookSource` for their path. Its
+ ``handle()`` verifies the signature, shapes a :class:`WorkflowEvent`
+ and wakes a waiting canvas Run; the plugin's override emits the event
+ to deployed triggers.
+2. **Generic webhook.** Paths no plugin claims reach ``webhookTrigger``
+ nodes through ``nodes/trigger/webhook_trigger/_events``.
+
+Both read the body through ``read_body_capped``, so a body larger than
+``WEBHOOK_MAX_BODY_BYTES`` is refused with 413 before it reaches a
+workflow.
"""
from fastapi import APIRouter, HTTPException, Request
@@ -19,6 +22,7 @@ import asyncio
import logging
from services.events import WEBHOOK_SOURCES
+from services.events.webhook import read_body_capped
# Wave 12 B9: webhook event dispatch moved to
# ``nodes/trigger/webhook_trigger/_events.broadcast_webhook_received``.
# The router no longer reaches into the broadcaster directly.
@@ -75,7 +79,7 @@ async def handle_webhook(path: str, request: Request):
logger.info("[Webhook] %s %s -> %s", request.method, path, type(source).__name__)
return JSONResponse({"status": "received", "path": path}, status_code=200)
- body = await request.body()
+ body = await read_body_capped(request)
json_body = None
content_type = request.headers.get("content-type", "")
diff --git a/server/services/events/webhook.py b/server/services/events/webhook.py
index 73cc8cec..10a6846a 100644
--- a/server/services/events/webhook.py
+++ b/server/services/events/webhook.py
@@ -33,6 +33,38 @@ logger = get_logger(__name__)
WEBHOOK_SOURCES: Dict[str, "WebhookSource"] = {}
+async def read_body_capped(request: Request) -> bytes:
+ """Read a webhook's body, refusing it with 413 past
+ ``WEBHOOK_MAX_BODY_BYTES`` (default in ``.env.template``).
+
+ The declared ``Content-Length`` refuses an honest oversized request
+ before any of it is read; the running total is what enforces the
+ limit, because the header is the caller's to set.
+ """
+ from core.env_defaults import env_int
+
+ limit = env_int("WEBHOOK_MAX_BODY_BYTES")
+ declared = request.headers.get("content-length", "")
+ if declared.isdigit() and int(declared) > limit:
+ raise _body_too_large(limit)
+ chunks: list[bytes] = []
+ total = 0
+ async for chunk in request.stream():
+ total += len(chunk)
+ if total > limit:
+ raise _body_too_large(limit)
+ chunks.append(chunk)
+ body = b"".join(chunks)
+ # Starlette's body cache: request.body() and request.json() now return
+ # these bytes instead of reading the consumed stream.
+ request._body = body
+ return body
+
+
+def _body_too_large(limit: int) -> HTTPException:
+ return HTTPException(status_code=413, detail=f"Request body is larger than the {limit}-byte webhook limit.")
+
+
def register_webhook_source(source: "WebhookSource") -> None:
"""Idempotent: same instance for the same path is a no-op; conflicts raise."""
existing = WEBHOOK_SOURCES.get(source.path)
@@ -90,8 +122,9 @@ class WebhookSource(PushEventSource):
async def handle(self, request: Request) -> WorkflowEvent:
"""Called by the webhook router. Verifies signature, parses the
body, shapes the event, dispatches into ``event_waiter``, and
- returns the event for logging / response shaping."""
- body = await request.body()
+ returns the event for logging / response shaping. Subclasses that
+ feed deployed triggers emit the returned event themselves."""
+ body = await read_body_capped(request)
if self.verifier is not None:
secret = await self._resolve_secret()
if not secret:
@@ -118,7 +151,6 @@ class WebhookSource(PushEventSource):
raise HTTPException(status_code=400, detail=f"invalid JSON body: {e}")
event = await self.shape(request, body, payload)
- await self.receive(event)
from services import event_waiter
diff --git a/server/tests/nodes/test_discord.py b/server/tests/nodes/test_discord.py
index 12d34b40..993bc9e2 100644
--- a/server/tests/nodes/test_discord.py
+++ b/server/tests/nodes/test_discord.py
@@ -845,6 +845,22 @@ class TestInteractionsEndpoint:
assert response.status_code == 200
assert response.json() == {"type": 1}
+ def test_a_body_over_the_webhook_limit_is_413(self, monkeypatch):
+ """The body would ride into a workflow's input (RFC-0004 C1)."""
+ monkeypatch.setenv("WEBHOOK_MAX_BODY_BYTES", "16")
+ private, public_hex = _keypair()
+ body = b'{"type":1,"pad":"' + b"x" * 32 + b'"}'
+ ts = "1700000000"
+ sig = private.sign(ts.encode() + body).hex()
+
+ response = self._post(
+ body,
+ {"X-Signature-Ed25519": sig, "X-Signature-Timestamp": ts, "Content-Type": "application/json"},
+ public_hex,
+ )
+
+ assert response.status_code == 413
+
def test_bad_signature_is_401_not_400(self):
"""Discord's endpoint-validation probe sends a deliberately invalid
signature and refuses to save the URL unless it gets a 401."""
diff --git a/server/tests/nodes/test_dodo_payments.py b/server/tests/nodes/test_dodo_payments.py
index 818a544c..a1e7858e 100644
--- a/server/tests/nodes/test_dodo_payments.py
+++ b/server/tests/nodes/test_dodo_payments.py
@@ -789,7 +789,7 @@ def _delivery(event_type: str = "payment.succeeded", *, msg_id: str = "msg_1", k
def _request(body: bytes, headers: dict):
- """An object with the two attributes WebhookSource.handle reads."""
+ """An object with the attributes WebhookSource.handle reads."""
class Request:
pass
@@ -800,7 +800,11 @@ def _request(body: bytes, headers: dict):
async def read():
return body
+ async def stream():
+ yield body
+
request.body = read
+ request.stream = stream
return request
diff --git a/server/tests/nodes/test_stripe_plugin.py b/server/tests/nodes/test_stripe_plugin.py
index 3e1ceaeb..02fb4d22 100644
--- a/server/tests/nodes/test_stripe_plugin.py
+++ b/server/tests/nodes/test_stripe_plugin.py
@@ -32,7 +32,7 @@ def _signed(body: bytes, secret: str) -> dict:
def _fake_request(body: bytes, headers: dict | None = None):
- """Return an object with the two attrs WebhookSource.handle uses."""
+ """Return an object with the attributes WebhookSource.handle reads."""
class R:
pass
@@ -43,7 +43,11 @@ def _fake_request(body: bytes, headers: dict | None = None):
async def _body():
return body
+ async def _stream():
+ yield body
+
r.body = _body
+ r.stream = _stream
return r
diff --git a/server/tests/routers/test_webhook.py b/server/tests/routers/test_webhook.py
index 7b03ee17..84a0e3da 100644
--- a/server/tests/routers/test_webhook.py
+++ b/server/tests/routers/test_webhook.py
@@ -120,6 +120,59 @@ class TestGetHandshake:
assert source.handled == 1
+class TestBodyCap:
+ """A body larger than ``WEBHOOK_MAX_BODY_BYTES`` is refused with 413
+ before it reaches a workflow: it would ride into the workflow's input,
+ which Temporal caps at 2 MB (RFC-0004 C1)."""
+
+ def test_a_declared_oversize_body_is_refused(self, client, clean_registry, monkeypatch):
+ monkeypatch.setenv("WEBHOOK_MAX_BODY_BYTES", "16")
+ clean_registry.clear()
+
+ with patch("nodes.trigger.webhook_trigger._events.broadcast_webhook_received") as broadcast:
+ resp = client.post("/webhook/unclaimed", content=b"x" * 17)
+
+ assert resp.status_code == 413
+ broadcast.assert_not_called()
+
+ def test_a_streamed_body_without_a_length_is_capped_by_what_arrives(self, client, clean_registry, monkeypatch):
+ monkeypatch.setenv("WEBHOOK_MAX_BODY_BYTES", "16")
+ clean_registry.clear()
+
+ def chunks():
+ yield b"x" * 10
+ yield b"x" * 10
+
+ with patch("nodes.trigger.webhook_trigger._events.broadcast_webhook_received") as broadcast:
+ resp = client.post("/webhook/unclaimed", content=chunks())
+
+ assert resp.status_code == 413
+ broadcast.assert_not_called()
+
+ def test_a_registered_source_is_capped_too(self, client, clean_registry, monkeypatch):
+ monkeypatch.setenv("WEBHOOK_MAX_BODY_BYTES", "16")
+ source = _RecordingSource()
+ clean_registry[source.path] = source
+
+ with patch("services.event_waiter.dispatch") as dispatch:
+ resp = client.post("/webhook/recording", json={"padding": "x" * 32})
+
+ assert resp.status_code == 413
+ dispatch.assert_not_called()
+
+ def test_a_received_event_is_not_left_on_a_queue_nothing_reads(self, client, clean_registry):
+ """``handle()`` used to put every event on the source's queue as well,
+ which nothing drained, so each webhook stayed in memory for good."""
+ source = _RecordingSource()
+ clean_registry[source.path] = source
+
+ with patch("services.event_waiter.dispatch"):
+ resp = client.post("/webhook/recording", json={"a": 1})
+
+ assert resp.status_code == 200
+ assert source._queue.empty()
+
+
class TestLegacyFallback:
def test_unclaimed_path_still_reaches_the_generic_handler(self, client, clean_registry):
"""An unregistered path must keep firing webhookTrigger nodes."""