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?