ADR 0013: No trailing-slash redirect on the webhook¶
- Status: Accepted
- Date: 2026-11-11
Context¶
The webhook path is the endpoint's only protection: anyone who knows it can open and close trades on the account. The README tells operators to put the bot behind a reverse proxy that terminates TLS, because the bot serves plain HTTP.
The inbound adapter builds a FastAPI app
(ADR 0010). Starlette's
router redirects by default: a request whose path differs from a route's
only by a trailing / gets a 307 Temporary Redirect to the other form.
For the default path:
POST /strategy/andPOST /strategy//got a307to/strategy;- with
url=/hook/,POST /hookgot a307to/hook/.
The redirect's Location is an absolute URL, and Starlette builds its scheme
from the request as uvicorn saw it. uvicorn 0.54 reads the scheme from
X-Forwarded-Proto only when the connection comes from an address it trusts,
by default 127.0.0.1 and ::1. A proxy in another container or on another
host is not trusted, so for the bot the request was plain HTTP and the
Location began with http://. A 307 keeps the method and the body, so a
sender that followed it sent the secret path and the signal again,
unencrypted, to a public address.
sequenceDiagram
participant S as alert sender
participant P as TLS proxy
participant B as bot (uvicorn, Starlette)
S->>P: POST https://host/strategy/ + signal
P->>B: POST /strategy/ over plain HTTP
alt before: the path differs by a slash
B-->>P: 307, Location: http://host/strategy
P-->>S: 307, Location: http://host/strategy
S->>P: POST http://host/strategy + signal, unencrypted
else now: no redirect
B-->>P: 404 {"detail":"Not Found"}, like any unknown address
P-->>S: 404, nothing sent again
end
Step 5a pinned the redirect as a known defect
(test_a_trailing_slash_is_redirected_to_the_path_without_handling). The
README advised operators to let the proxy forward only the exact path, so
the bot never saw the other form.
Decision¶
Build the app with redirect_slashes=False:
FastAPI(openapi_url=None, redirect_slashes=False).
- A path that differs from the webhook path by a slash, added or missing,
answers
404with{"detail":"Not Found"}and the same headers as any address the app does not serve. It starts no thread and makes no broker call. - The webhook path itself is unchanged: the same method, answer, body decoding and thread per request.
- The
urlsetting already means one exact path: the README's troubleshooting says an alert's URL must match it exactly, case included. The redirect was the one exception, and it is gone.
What changes¶
This is a behaviour change.
| Request | Before | After |
|---|---|---|
POST /strategy |
handled, 200 |
handled, 200 |
POST /strategy/, POST /strategy// |
307 to http://…/strategy |
404 |
GET /strategy/ |
307 to http://…/strategy |
404 |
POST /hook with url=/hook/ |
307 to http://…/hook/ |
404 |
An alert whose URL differs from url by a slash may have worked until now,
if its sender followed the 307 and the plain-HTTP request reached the bot.
It now gets 404. The fix on the operator's side is to make the alert's URL
match url exactly, which the README already asks for.
The tests changed with it:
- The pin is replaced in
tests/characterization/test_webhook_route.py:POST /strategy/andPOST /strategy//answer like an unknown address, with no redirect followed, no thread and no broker call. The requests are sent by a client that follows redirects, as such a sender does, so a redirect back would be handled and fail the test. - The other direction is pinned: with
url=/hook/,POST /hookgets404andPOST /hook/is handled. GET /strategy/joins the methods and paths that never reach the handler, at404.
All four failed against the redirect before the fix.
What this does not cover¶
-
uvicorn's access log still writes the path of every request. It is a known defect of its own in the migration roadmap.
Update: step 6f (ADR 0016) drops the request line, and with it the path, from the access line. - A
urlwithout a leading/is still accepted at startup and never matches a request. It is the next known defect, in the same lines of the README, so it gets its own step.Update: step 6d (ADR 0014) refuses such a
urlat startup. - Plain HTTP between the proxy and the bot stays as it is. The bot no longer tells a sender to use it, but the README's advice to terminate TLS in front of the bot, on the same host or network, still holds.
Consequences¶
- The bot never sends a sender to another address. A
POSTeither matches the path exactly or gets the same404as any address the app does not serve, so a path one slash away no longer confirms that the webhook is there. - Forwarding only the exact webhook path from the proxy is still good practice, but no longer needed to stop a redirect.
- Images built before this step still redirect. The README's earlier advice applies there: forward only the exact path, and use it in the alerts.
Alternatives considered¶
- Trust the proxy's headers (
forwarded_allow_ips="*"in uvicorn), so theLocationsayshttps://. Rejected:- uvicorn would then believe
X-Forwarded-ForandX-Forwarded-Protofrom anyone who reaches the bot directly; - it only helps if the operator's proxy sends the header;
- it keeps a redirect that sends the signal twice, and the server options are part of the pinned startup.
- uvicorn would then believe
- Serve both forms of the path. Rejected: it adds a second address that handles signals, one the operator never configured, and breaks the "exact path" rule the README states.
- Keep the redirect with a relative
Location. Rejected: Starlette has no option for it, so it needs custom code to keep a convenience that the contract never promised. - Leave it to the reverse proxy, as the README advised. Rejected as the only defence: a bot reached directly, or behind a proxy that forwards every path, still redirected.