Skip to main content
← Back to list
01Issue
BugShippedSwamp CLIPublic
Assigneesskunk-apezack

Relationships

#4407 serve: a webhook route can shadow serve's own API paths; require a fixed route prefix

Opened by skunk-ape · 11/4/2026· Shipped 11/9/2026

Closed: superseded by #4547. The fix for this issue (#3688) was reverted the same day (#3692). Operators may define a webhook on any path, and swamp-uat relies on routes under /api/v1/hooks/. The /hooks/ prefix now applies only to webhook route files (#4547). serve.yaml and --webhook routes keep the leading-slash check only. The Decision and Proposed change below are no longer current.

Problem

Webhook routes are matched before serve's HTTP API. The only validation on a route is that it starts with a slash (src/serve/serve_config.ts:812 and src/serve/webhook.ts:281), so a route can take over a POST path that serve itself answers.

Reproduced

On 3ff9a7030, against a scratch repo on loopback:

  • With a route at /hooks/x, POST /api/v1/cancel returned 200 with cancellation_requested.
  • With a route at /api/v1/cancel, the same request returned 401 Missing x-hub-signature-256 header, and serve logged the route as registered with no warning.

Only whoever controls the serve config can create a route today, so this is a misconfiguration risk rather than something an outside caller can trigger. It has to be closed before anyone other than the operator can create routes (see #3434).

Decision

Webhook routes always live under a fixed prefix, so they can never shadow a server route, now or as serve adds paths. The prefix is not optional and not disableable.

Proposed change

  • Define one constant prefix, /hooks/. It fits existing usage: 102 of the 109 routes in the manual, the source tree, integration tests and swamp-uat already use it. The one non-prefixed example in the manual is a --webhook /deploy example.
  • Enforce it in both places routes enter: serve.yaml webhooks (including reload and check-config) and --webhook flags.
  • Refuse a route that is the bare prefix, or that has empty, dot or dot-dot segments.
  • Add an architecture fitness test so no serve HTTP route can be added under the prefix.

Open question

Deployed routes outside the prefix are senders' configured URLs and cannot be seen from here. Refusing them at boot on upgrade would stop a serve, so this needs a migration decision: refuse immediately, or warn for a release and then refuse. A reload that finds an invalid route keeps the previous route table, as it does today.

Out of scope

An additional admin-configured prefix layer, and stored routes; both belong to the design in #3434. Moving a route needs its sender's URL changed, so a manual update belongs in a sibling swamp-club issue.

02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 3 MOREASSIGNED+ 7 MOREFINDINGS+ 20 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/9/2026, 5:08:35 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
skunk-ape assigned skunk-ape11/4/2026, 9:38:12 PM
zack assigned zack11/9/2026, 3:56:06 PM

Sign in to post a ripple.