version: "1.0.0"

Setup tips & tricks: Linear × Claude Managed Agents webhook bridge

Things that aren't obvious from the docs and tend to cost debugging time.

Mental model

A webhook is "call me when something happens"

It's an HTTP POST a service sends to a URL you gave it, with a small JSON body describing an event. You register the URL once, and the service calls it whenever the event fires. No polling, no held-open connections.

The bridge is mandatory (today)

Linear's Agent Platform and Managed Agents don't share a wire format or credentials. Something has to translate "Linear @mention" → "user.message" on the way in, and "session idle" → "Linear comment" on the way out, while holding both sets of keys. That's the bridge.

Two webhooks, one bridge

• Linear → bridge (/linear-webhook) fires on @mention or assignment. Payload carries agentSession.id, organizationId, and issue context.
• Anthropic → bridge (/managed-agents/webhook) fires on session idle. Payload carries only the session ID.

Neither carries a "callback URL." Neither carries the agent's output. Both are signals with IDs.

The webhook is a doorbell, not a delivery

Anthropic's session.status_idled payload is deliberately thin: {type, id}. You always follow up with sessions.retrieve(id) (to get metadata) and sessions.events.list(id) (to get the output). Push the signal, pull the data. Retries stay cheap and data is never stale.

metadata is the entire routing state

When the bridge creates the session it sets metadata: {linear_session_id, linear_org_id}. When the idle webhook arrives later with only a session ID, the bridge retrieves the session, reads those keys back, and knows exactly where to reply, with nothing stored in the bridge itself. This is what makes it stateless.

Gotchas

Anthropic webhooks are workspace-scoped

The endpoint you register in Console only receives events for sessions in that same workspace. If your Anthropic credentials belong to workspace A but you registered the endpoint in workspace B, you get zero deliveries, silently. Match the workspace picker on the Console's Webhooks page to the Workspace column on your API key, or to the workspace ant auth login signed you into.

A workspace webhook fires for every session in the workspace

Not only yours. If the Anthropic workspace is shared with other agents, scripts, or teammates, every session.status_idled in that workspace hits your endpoint. Your handler must filter: sessions.retrieve(id) → check for your metadata keys → return 204 for anything that isn't yours. Also catch 404/403 on sessions.retrieve, and only those. Sessions created under other API keys in the same workspace aren't readable by yours, but a 429 or 5xx is a real failure that should be retried.

Corollaries: subscribe only to the event types you need (session.status_idled, session.status_terminated), not "All events". For production, consider a dedicated Anthropic workspace so there are no unrelated sessions to discard.

Linear OAuth apps are workspace-admin-only

OAuth apps live at linear.app/<your-workspace>/settings/api. In the sidebar it's Administration → API, then the OAuth Applications section. If you're not an admin of your company workspace, spin up a free personal workspace for testing. It takes two minutes and you won't install an experimental agent into production.

When creating the app, the Developer URL field is required but cosmetic (it's a link shown on the consent screen). Any real https:// URL is fine.

actor=app is the load-bearing OAuth parameter

scope=app:assignable,app:mentionable + actor=app is what creates an app user in the Linear workspace that shows up in the @-picker. A personal LINEAR_API_KEY won't do this. The bridge must post back as the app, via the OAuth token.

BASE_URL has to match the callback URL exactly

src/oauth.ts builds the redirect URI as ${BASE_URL}/oauth/callback and sends it on both the authorize redirect and the token exchange. Linear rejects the exchange unless it matches the callback URL registered on the OAuth app character for character. A new ngrok URL means updating both .env and the Linear app.

The first install owns the bridge

/oauth/authorize has no login in front of it. Anyone who can reach the server could install the agent into a Linear workspace they administer, and from then on every mention there would run a session on your Anthropic credentials. So the gate fails closed. With LINEAR_ALLOWED_ORG_IDS unset, the first workspace to install is the only one the bridge serves: a later install from a different workspace gets a 403 and its token is revoked, and webhook events from it are ignored. Install your own workspace right after you start the server, and check the log line names it.

Set LINEAR_ALLOWED_ORG_IDS to a comma-separated list of organization IDs to pin that choice or to serve more than one workspace. The server logs the organization ID on each install. To hand the bridge to a different workspace, delete .linear-tokens.json and install again.

The flow also uses a single-use state value that expires after 10 minutes, so a callback only succeeds if this server started it. Restarting the server forgets pending states. If you see "Unknown or expired state", start again at /oauth/authorize.

The idle webhook only trusts routes it signed

metadata says where to reply, but it does not prove the session is the bridge's. Anyone with credentials for the same Anthropic workspace can start a session, on this same agent, with linear_session_id and linear_org_id of their choosing. A handler that trusted those keys would post their text into your Linear issue with your token. Checking session.agent.id and session.environment_id is a useful first filter and nothing more, because agent IDs are not secrets.

So at kickoff src/agent.ts stores linear_route_sig, an HMAC over the Claude session ID, the Linear session ID, and the organization ID, keyed by a secret derived from LINEAR_CLIENT_SECRET, which never leaves the bridge. src/managed-agents-webhook.ts recomputes it and compares in constant time before posting anything. The Claude session ID is part of the signed text on purpose: metadata is readable by the same people who can forge it, so a signature over the route alone could be copied onto another session. The signature is also single-use. A signed session is still a session that anyone with workspace credentials can send another message to, and its next idle would post their text into the issue. So once the bridge has delivered, or decided it never will, it deletes linear_route_sig from the metadata, and later idles are refused. A retryable failure leaves it in place so the retry can still verify. The bridge also remembers delivered sessions in memory and takes a per-session lock right after verifying, because the remote delete can fail and two idle events for one session carry different event ids. And the signed text includes an issued-at time: a route older than 24 hours is refused, so one whose delivery keeps failing does not stay live with no end. An agent run longer than that loses its reply. Raise MAX_AGE_SECONDS in src/route-signature.ts if yours do. If you fork this, keep the verify call between the metadata read and the first Linear call, and keep the delete after the delivery. Rotating LINEAR_CLIENT_SECRET invalidates the signatures of sessions still running, and their replies are dropped with a log line.

Issue text is untrusted input

The prompt is the issue title, description, and comments, which anyone with access to the Linear workspace can write. src/agent.ts wraps each piece in a tag such as <linear_issue_description> and the system prompt tells the agent to treat tagged text as data. That lowers the odds that an injected instruction is followed. It does not remove them. The agent has the full toolset (bash, web fetch) with always_allow, in a sandbox with unrestricted egress, and nobody approves a step. Treat it like running a script a stranger wrote: keep secrets out of the sandbox, and if you mount a repo or add MCP tools, scope their credentials to what a hostile issue should be able to touch. environments/linear-assistant.yaml is where to switch networking to limited with an allowlist.

Linear's 10-second ack rule

The bridge must post some agentActivity (a {type: "thought"} is enough) within 10 seconds of receiving the AgentSessionEvent, or Linear marks the session failed. Do this before creating the Managed Agents session.

event.id is your idempotency key

Anthropic retries failed deliveries with the same top-level event.id. Dedupe on it, but only mark an id handled once handling finished. If it threw, the retry has to be processed or the reply is lost. A duplicate that arrives while the first attempt is still running gets a 503, not a 204: acking it would mark the event delivered while the outcome is still unknown. Return 2xx once you've either handled it or decided to ignore it. Anything else triggers a retry, and ~20 consecutive failures auto-disables your endpoint. That is why a Linear error a retry can't fix (no token for the org, a revoked install or a refused token refresh, an agent session Linear has closed) is logged and acked instead of thrown.

Stop interrupts the run, best effort

Linear sends Stop as a prompted event whose activity carries signal: "stop". Treated as a prompt, it would start a second session. src/agent.ts remembers which Claude session is working on each Linear session, sends that session user.interrupt, posts "Stopped.", and the idle webhook then skips the interrupted run's half-finished text.

That map is the one piece of state the bridge keeps, and it lives in memory. After a restart the bridge has no record of runs started before it, so Stop says exactly that instead of claiming a stop that did not happen. Reply routing never depends on the map. It still reads metadata. For production, keep linear_session_id → session.id in Redis or a DB.

No approval surface, so tools are always_allow

agents/linear-assistant.md sets permission_policy: {type: always_allow} on the toolset. An always_ask tool idles the session to wait for a confirmation, the idle webhook fires, and the bridge posts whatever partial text exists. If you add an approval flow (Linear's elicitation activity plus user.tool_confirmation), switch the risky tools back to always_ask.

Signature header names

The docs say X-Webhook-Signature. The wire uses Webhook-Signature / Webhook-Id / Webhook-Timestamp (Standard Webhooks spec). The SDK's webhooks.unwrap() handles this, so it only matters if you're verifying by hand.

Local dev checklist

1. ngrok http 3000 (or cloudflared tunnel) → note the public URL and set it as BASE_URL in .env (cp .env.example .env first). Everything below uses it.
2. ant auth login (or export ANTHROPIC_API_KEY), then ant apply agents environments. It creates the agent and environment and writes their IDs to claude-lock.json, which the bridge reads at startup. Nothing to paste into .env for them.
3. Linear OAuth app (Administration → API → OAuth Applications → Create new): Developer URL = any real https:// URL (cosmetic). Callback <url>/oauth/callback. Webhook <url>/linear-webhook, events = Agent session events → copy client ID/secret + webhook secret into .env.
4. Claude Console → Manage → Webhooks: <url>/managed-agents/webhook, events = session.status_idled + session.status_terminated → copy whsec_… → ANTHROPIC_WEBHOOK_SIGNING_KEY. Same workspace as your Anthropic credentials.
5. bun run dev.
6. Visit <url>/oauth/authorize → approve → "Agent installed." The server logs [oauth] installed in "<name>" (<org-id>). That workspace now owns the bridge. Put the ID in LINEAR_ALLOWED_ORG_IDS to pin it.
7. @mention it in an issue.

Debugging a silent failure

• "Thinking…" never appears → Linear webhook isn't reaching you. Check the Linear app's webhook URL and that ngrok is up. If the log shows ignored event from org …, a different workspace installed first or that workspace isn't in LINEAR_ALLOWED_ORG_IDS.
• "Thinking…" appears but no reply → check curl localhost:4040/api/requests/http (ngrok's request log). If no POST to /managed-agents/webhook: workspace mismatch on the Anthropic side, or endpoint not saved. If POST arrives with 401: signing key mismatch. If the log shows could not post to linear=…: the message names the cause, usually a missing .linear-tokens.json entry (reinstall at /oauth/authorize).
• `FATAL: … .linear-tokens.json is not valid` at startup → the token file is corrupt. The bridge refuses to start on it, because reading it as empty would let any workspace install. Fix the JSON, or delete the file and reinstall at /oauth/authorize.
• `FATAL: no agent or environment ID` → ant apply agents environments hasn't run in this directory yet, so there is no claude-lock.json beside package.json, or it stopped partway and the lockfile lacks one of the two (run it again and read its error). If you ran it from another directory, the lockfile is there instead: run it again from here.
• `ant apply` fails with 409 on the environment → environment names are unique per workspace and someone already created quickstart-linear-assistant-env there (an earlier run of this quickstart's old agents/setup.sh, usually). The environment is created first, so the agent was not created either. ant apply can't adopt an existing resource: change name in environments/linear-assistant.yaml and run ant apply agents environments again. To reuse the existing environment instead, delete environments/linear-assistant.yaml, set its ID as CLAUDE_ENVIRONMENT_ID in .env, and run ant apply agents.
• The agent answers with an old prompt or model → check the Using agent ... (from ...) line the bridge prints at startup. from CLAUDE_AGENT_ID means there is no claude-lock.json entry and an ID from .env is in use (an older setup of this bridge wrote IDs there): run ant apply agents environments here, or delete the stale lines.
• `Linear refused to refresh the token for org …` in the log → Linear answered invalid_grant: the workspace uninstalled the app. Reinstall at /oauth/authorize. An invalid_client in the log instead means LINEAR_CLIENT_SECRET is wrong.
• "Linear rejected the install" after approving → the server log has Linear's response. The usual cause is BASE_URL not matching the app's callback URL.
• The bot answers with an old prompt or model → Bun loads .env.local over .env. If you have one left from the cookbook version of this bridge, delete it.

Production notes

• Replace ngrok with a real deploy (Cloudflare Workers, Fly, etc.). Nothing else changes.
• Replace the in-memory seenEventIds Set and the pending OAuth state map with Redis or a DB for multi-instance deploys.
• Replace the .linear-tokens.json file with a real secret store. The bridge writes it owner-only (0600) and replaces it atomically, which is enough for a laptop and not for a server.
• Narrow the Anthropic endpoint's event subscription to exactly what you handle.