mode: webhook channel is served through the gateway’s single listener at /webhooks/<channel> — one port, one public URL, routed by path.
Quick Start
1
Declare webhook channels — no port on any
Leave
webhook_port unset and every mode: webhook channel shares gateway.port.2
Opt out — pin one channel to its own port
Set
webhook_port on a channel to restore a standalone server for just that channel.How It Works
An external service POSTs to/webhooks/<channel>; the gateway verifies the signature per-channel, then dispatches to the agent.
Each channel keeps its own verifier — a bad signature on one channel returns 401 without touching the others. An unknown path returns 404 with no cross-channel fallthrough. Hot-reloading a channel re-mounts /webhooks/<channel> automatically; removing a channel clears its mount — no process restart.
When do I set webhook_port?
Configuration Options
webhook_port selects shared vs. standalone mode on any mode: webhook channel.
Common Patterns
Multi-provider on one URL
Point GitHub, Stripe, and a generic billing hook at one public URL — the path picks the channel.https://bots.example.com/webhooks/github, .../webhooks/stripe, .../webhooks/billing_hook.
Reverse-proxy termination for one HTTPS URL
Terminate TLS at your proxy and forward one path prefix to the gateway.Explicit-port opt-out for a legacy tunnel
A tunnel already pinned to a fixed port keeps working — setwebhook_port on that one channel.
Best Practices
Set an HMAC secret per channel
Set an HMAC secret per channel
The gateway delegates verification to each channel’s own verifier, fail-closed — a bad signature returns
401. Give every webhook channel its own verify.hmac.secret.Don't set webhook_port unless you need isolation
Don't set webhook_port unless you need isolation
An explicit port opts a channel out of the shared listener and back onto a standalone server. Use it only for a legacy tunnel pinned to one port, or when one channel needs process isolation.
Rely on automatic re-mount after hot-reload
Rely on automatic re-mount after hot-reload
After a hot-reload,
/webhooks/<channel> re-mounts automatically and a removed channel’s mount is cleared — no restart required.Related
Webhook Channel
Route any HTTP webhook to an agent with a YAML route
Webhook Verification
The HMAC signature primitive each channel verifies fail-closed
Gateway Overview
Gateway architecture and the single listener
Gateway Inbound Hooks
/hooks/<path> generic triggers — the ad-hoc counterpart to /webhooks/<channel>