Skip to main content
← Back to list
01Issue
FeatureShippedSwamp ClubPublic
AssigneesNone

Relationships

↔ sibling #4556

#4551 Docs: serve skips webhook routes under its reserved path roots; recommend /hooks/

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

What changed

swamp-club#4407 stops a webhook route from shadowing serve's own HTTP paths. Serve now skips a webhook route (from serve.yaml webhooks or --webhook) that:

  • is the root path itself, or sits at or under a reserved root: health, ready, auth, api, internal, dashboard, data, bundle. Matching is on the first non-empty path segment, so /apiary is fine while /api and /api/github are skipped. A percent-encoded spelling of a root (such as /%61pi/x) is skipped too.
  • has a dot or dot-dot segment (such routes could never match a delivery).

Only that webhook fails: serve starts and serves every other route, logs 'Webhook route skipped' (webhook_skipped in --json) with the reason, swamp serve reload applies the other routes and reports a warning, and swamp serve check-config lists it under Webhook warnings without failing.

Every other route stays valid, including existing routes outside /hooks/ such as /deploy. /hooks/ is reserved for webhooks: serve never adds its own route under it, so it is the recommended prefix for new routes.

Pages to update

  • content/manual/reference/swamp-serve/webhooks.md: in the route row of the flag table, state the reserved roots, the dot-segment rule, that such a route is skipped, and that /hooks/ is recommended.
  • content/manual/how-to/set-up-webhooks.md: recommend /hooks/ routes, and explain that a route under a reserved root is skipped (with a warning at startup, on reload and in check-config); moving it means changing the sender's configured URL.
  • Any example using --webhook /deploy stays valid, but prefer a /hooks/ route in new examples.
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPEDLINKED+ 3 MOREPR_LINKED+ 1 MORESESSION_SUMMARIZED

Shipped

11/10/2026, 7:10:29 AM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 linked sibling of #455611/9/2026, 11:33:49 PM

Sign in to post a ripple.