Webhook URLs for agents when the operator runs their own ingress markdown

[boblangley]

Summary

Webhook tasks work without T3 Connect: the server accepts requests at /api/hooks/:taskId/:token. But an agent that creates a webhook task with schedule_task only gets a webhookUrl when the environment has a T3 Connect managed tunnel. If I expose T3 through my own ingress, the agent gets nothing it can share or configure, so a human has to copy the path from the task editor.

I'd like agents to get a callable URL when the operator has their own ingress.

Use case

Anyone who exposes their T3 environment with their own ingress instead of T3 Connect: cloudflared, ngrok, Pinggy, Tailscale Funnel or Serve, a reverse proxy, and so on. The webhook route works fine through all of these. What's missing is that T3 doesn't know the public origin, so it can't build a URL for agents.

A local sender on the same machine, such as a workflow engine or a CI runner, is the simplest case of the same problem: the URL is http://127.0.0.1:<port>/api/hooks/..., and the agent can't learn it.

For example, my own setup puts a hosted queue (QStash) in front of a local bridge (Trowel) that delivers to T3 on the same host, which gives me held delivery and retries. That part is my own choice; any ingress has the same gap.

What is unclear

• OrchestratorMcpService says "A bare path is not a URL anyone can call, so agents never get one to share." The schedule_task description tells agents to ask the user to enable T3 Connect rather than share a path.
• Webhook-triggered scheduled tasks via the T3 Connect relay #14733 asked: "Would you want a direct-ingress option for non-Connect setups, and if so, in this effort or separately?" It was closed when feat(server): scheduled tasks can run on a webhook #15085–feat(web): create webhook automations and inspect their deliveries #15088 landed, without an answer to that question.
• fix(server): expose direct webhook paths to agents #16951 added an optional webhookPath for agents, behind the same permission checks as webhookUrl. The review asked a maintainer to confirm whether withholding the path was intentional. It was closed without an answer.

Proposed approach

Let the operator set a webhook base URL in environment settings, such as https://hooks.example.com. When it is set and there is no relay base, webhookUrl is built from it the same way it is built from the relay base today: <base>/api/hooks/<taskId>/<token>.

• It keeps the current rule: agents only get URLs someone can call, and the operator chose the origin.
• It uses the same access checks as today: orchestration:operate scope, and a caller that may run the task.
• The web and mobile editors can show the full URL instead of only the path.
• Connect users are unaffected.

Alternatives, if a setting isn't wanted:

1. Return an optional webhookPath to agents (the fix(server): expose direct webhook paths to agents #16951 shape), with tool guidance to treat it as a bearer credential: plain HTTP only on loopback, and HTTPS or an authenticated tunnel for anything remote.
2. Return a loopback URL built from the server's own listen address, for same-host senders only.

Questions

1. Is withholding a usable webhook URL from agents in non-Connect setups intended?
2. If not, is an operator-set base URL acceptable, or would you prefer one of the alternatives?
3. Should the server enforce anything about the base URL, such as requiring https unless it is loopback?

[yair]

We have the same gap, from a different direction: several machines on a private Tailscale network, each running its own T3 environment. Agents on one machine message threads on another by POSTing to webhook tasks bound to those threads. The route itself works fine for this. Only the URL is missing, so we fill it in outside T3: a hook calls the client API with a scoped token and builds <backend's tailnet address>/api/hooks/<taskId>/<token> itself. That is the operator-set base URL proposed here, done the long way round.

On the questions:

1. Is withholding intended? If the concern is handing agents a credential, the Connect URL they already get is a credential too, and it is reachable from the whole internet. A base URL the operator chose reaches no more senders than the operator already exposed, often far fewer (loopback, a tailnet). Withholding it doesn't reduce exposure; it only means non-Connect setups have to rebuild the URL outside T3.
2. Base URL or an alternative? An operator-set base URL fits us. One value per environment is enough, because every machine on the tailnet reaches a backend by the same name.
3. Enforce https unless loopback? That would rule out our setup: we use plain HTTP inside the tailnet, where WireGuard already encrypts and authenticates every connection. Getting certificates for machines on a private network takes real tooling; we've had to build some for other services, and we'd rather not need it here. A warning in the settings form for a non-loopback http base would cover the risk without blocking private networks.

Related: the webhook filters from #22194 fixed our other rough edge. A malformed POST became an empty turn; a filter on body.text will drop those before they start a run.

Written with Claude Opus 5.5 in Claude Code.