Skip to main content
← Back to list
01Issue
FeatureShippedSwamp CLIPublic
Assigneeszack

Relationships

#4547 serve: load webhook routes from reviewed files in the repo

Opened by zack · 11/9/2026· Shipped 11/9/2026

Problem

Today a webhook route can only be declared on the serve host: a webhooks[] entry in .swamp/serve.yaml or a --webhook flag. Adding a webhook therefore means editing host configuration, with no code review. There is no way to add a route through a reviewed repo change.

Proposed solution

Load webhook routes from YAML files in a repo directory, one route per file. Code review on the PR is the gate. After the change reaches the serve host, swamp serve reload makes the route live. Deleting the file removes the route.

Each file carries the same fields as WebhookConfigEntry (src/serve/serve_config.ts): route, workflow, secret, scheme, header, prefix, config.

Rules

  • Secrets: a route file accepts only @vault=<vault>:<key>. A literal secret (or @env= / @file=) is refused, and the error names the file and the route. Today resolveSecret (src/serve/webhook.ts) uses any string without a prefix as the literal secret.
  • Clashes: two files claiming the same route is a load error naming both files.
  • Precedence: a serve.yaml or --webhook route on the same path wins over a file route, and the file route shows as shadowed.
  • Source label: routes from files report file:<name> in health output and on the dashboard. WebhookRouteSource is "config" | "flag" today.
  • No routes from extensions: the loader never reads extension directories, pulled or local. Add an architecture rule test that fails if anything registers a route from an extension, so pulling a public extension can never open an endpoint.
  • Loads at startup and on swamp serve reload, using the existing route-change path (src/serve/webhook_reload.ts).
  • File routes follow the same reserved-path rules as other routes (see #4407).

Naming (settle in triage)

The proposal's working names were a webhooks/ directory and a --webhooks-dir option. These collide with the existing webhooksDir / SWAMP_WEBHOOKS_DIR (src/cli/resolve_webhooks_dir.ts), which point at webhook extension code (extensions/webhooks). Since the loader must never read extension directories, near-identical names make that rule easy to break. Candidates: webhook-routes/ with --webhook-routes-dir.

Out of scope

  • Polling the directory (separate issue).
  • Refusing extension schemes from untrusted collectives (separate issue).
  • Routes declared in workflow files, a remote webhook set command, and routes stored in the datastore.
  • Validating inputs before queueing (422).

#3434 (reload can add the first route, X-Swamp-Run-Id, route source in health), #4407, #2234.

02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 8 MOREREVIEW+ 28 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/9/2026, 7:02:55 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
zack assigned zack11/9/2026, 3:49:55 PM
Editable. Press Enter to edit.

zack commented 11/9/2026, 3:49:18 PM

Sibling issues from the same proposal: #4548 (refuse untrusted extension schemes on any route; independent) and #4549 (optional polling of the route directory; depends on this one).

Sign in to post a ripple.