#19785: fix(gateway): support query parameter tokens for webhooks
app: macos
gateway
size: S
Cluster:
Security Enhancements and Guardrails
## Summary
Many webhook providers (OpenPhone, Twilio, Stripe, etc.) don't support custom headers and only allow authentication via URL query parameters.
This change adds support for `?token=` query parameter as a fallback when `Authorization` header or `X-OpenClaw-Token` header are not present.
## Changes
- Modified `extractHookToken()` to accept optional URL parameter
- Added query parameter token extraction as fallback
- Removed explicit rejection of query parameter tokens in hook handler
## Security Note
Query parameter tokens are less secure than header-based auth because they may appear in logs. However, this is a necessary compromise for webhook compatibility with common providers.
Users should be aware of this trade-off when using query parameter authentication.
## Testing
- Tested with OpenPhone/QUO webhooks
- Webhook with `?token=<hook_token>` now works correctly
- Header-based authentication still takes precedence
## Use Case
This enables integration with services like:
- OpenPhone/QUO
- Twilio
- Stripe
- Many other webhook providers that don't support custom headers
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Adds support for query parameter authentication as a fallback for webhook providers (OpenPhone, Twilio, Stripe, etc.) that don't support custom HTTP headers. Header-based auth (`Authorization: Bearer` and `X-OpenClaw-Token`) still takes precedence.
- `extractHookToken()` in `hooks.ts` now accepts an optional `URL` parameter and checks the query string for a token as a last-resort fallback
- The explicit 400 rejection of query parameter tokens in `server-http.ts` is removed, replaced by passing the parsed URL into `extractHookToken()`
- No test updates were included for the new query parameter fallback path in `extractHookToken`
<h3>Confidence Score: 4/5</h3>
- This PR is safe to merge — the change is minimal, correct, and intentional. The security trade-off of query parameter tokens is well-documented.
- Score of 4 reflects a clean, small change with correct logic and proper fallback ordering. Deducted one point because no tests were added for the new query parameter fallback path, though the logic is straightforward enough that this is low risk.
- No files require special attention.
<sub>Last reviewed commit: ed82362</sub>
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#8121: fix(gateway): remove query parameter token support for hooks
by yubrew · 2026-02-03
84.6%
#18273: fix: extract token from URL query string for Control UI websocket auth
by MisterGuy420 · 2026-02-16
78.6%
#6405: feat(security): Add HTTP API security hooks for plugin scanning
by masterfung · 2026-02-01
75.5%
#13144: harden archive extraction, auth tokens, hook transforms, and queue ...
by qxlsz · 2026-02-10
74.0%
#21050: security(voice-call): path-based stream token for Twilio WebSocket ...
by richvincent · 2026-02-19
73.9%
#9403: feat(hooks): Support application/x-www-form-urlencoded content-type...
by chipgpt · 2026-02-05
73.5%
#14197: fix(security): harden browser API auth, token comparisons, and hook...
by leecarollyn-gif · 2026-02-11
73.0%
#19885: test(gateway,browser): isolate tests from ambient OPENCLAW_GATEWAY_...
by NewdlDewdl · 2026-02-18
72.7%
#10093: fix: import gateway token from URL param into localStorage
by devjiro76 · 2026-02-06
72.5%
#17279: fix: restore device token priority over config token
by MisterGuy420 · 2026-02-15
71.8%