@trigger.dev/sdk 4.7.3 → 4.8.0-webhooks.20261015065339

package/docs/webhooks/deliveries.mdx

@@ -0,0 +1,92 @@
+---
+title: "Deliveries and endpoints"
+description: "Inspect webhook payloads, where each delivery went, and the runs it started or resumed."
+sidebarTitle: "Deliveries and endpoints"
+---
+
+**A delivery records a verified webhook event and what happened to it at each subscriber.** Find deliveries on an endpoint's **Deliveries** tab. A run that a delivery triggered links back to it, and to its endpoint, from the run's **Detail** tab.
+
+## Endpoints
+
+The environment's **Webhooks** page lists its endpoints with their URL, whether the signing secret is set, the last 24 hours of activity, and the last delivery. Open an endpoint for its tabs:
+
+| Tab | Shows |
+| --- | --- |
+| **Deliveries** | The endpoint's deliveries, filterable by status and time. |
+| **Subscribers** | Every task, agent session and channel subscribed to the endpoint, with each one's filter. |
+| **Waiters** | Runs currently [waiting](/webhooks/waiters) on the endpoint. |
+| **Test** | Sends a sample event through the endpoint. |
+
+The endpoint's details show its URL, source, verification scheme and signing secret actions. See [Connect a provider](/webhooks/connect).
+
+### Disable an endpoint
+
+Disable an endpoint to stop accepting its deliveries without removing it from your code. Its status becomes `inactive` and its URL responds with `404`, so the provider records failed deliveries and retries them on its own schedule:
+
+```bash
+curl -X POST "https://api.trigger.dev/api/v1/webhooks/endpoints/stripe/disable" \
+  -H "Authorization: Bearer $TRIGGER_SECRET_KEY"
+```
+
+[Enable](/management/webhooks/enable-endpoint) it again with `POST /api/v1/webhooks/endpoints/{endpointId}/enable`. An endpoint that is no longer in the environment's current deployment is also `inactive`.
+
+## Delivery status
+
+| Status | Meaning |
+| --- | --- |
+| `PENDING` | Waiting to be routed, including after a retryable error at a subscriber. |
+| `PROCESSING` | Being routed. A delivery that resumes many waiting runs stays here until they have all been resumed. |
+| `SUCCEEDED` | At least one subscriber or waiting run received it, and nothing failed. |
+| `FAILED` | A subscriber failed after its retries. The delivery's error names it. |
+| `FILTERED` | No subscriber's filter matched, or the endpoint has no subscribers. The reason shows the failed clause. |
+| `UNMATCHED` | Runs were waiting on the endpoint, but none matched and no subscriber took it. |
+
+Delivery status tracks routing. Each run it started has its own status and retry history.
+
+## Where a delivery went
+
+Open a delivery to see its payload and headers, and a row per subscriber with its result (`SUCCEEDED`, `FILTERED` with the reason, or `FAILED` with the error) and a link to the run it started. Waiting runs are summarized in one row: how many waiters matched, how many were resumed, and how many failed to resume.
+
+A subscriber that fails transiently is retried on its own; subscribers that already succeeded are not run again.
+
+## Replay
+
+Replaying a delivery routes its event again as a new delivery. Filters are checked again, so the replay reaches the subscribers that would take the event now:
+
+```bash
+curl -X POST "https://api.trigger.dev/api/v1/webhooks/deliveries/whd_1234/replay" \
+  -H "Authorization: Bearer $TRIGGER_SECRET_KEY"
+```
+
+Add `?targetId=` to send it to one subscriber regardless of its filter. `targetId` is the subscriber id: a `webhook()` task's id, or `agentId:eventId` for an agent's `chat.event` or channel. A replay never resumes waiting runs.
+
+## From an agent or the API
+
+The [MCP server](/mcp-introduction) has `list_webhook_deliveries` (filter by endpoint, status and time), `get_webhook_delivery` (each subscriber's result, the waiter summary, the event and headers) and `replay_webhook_delivery`. The same data is on the REST API:
+
+| Request | What it does |
+| --- | --- |
+| [`GET /api/v1/webhooks/deliveries`](/management/webhooks/list-deliveries) | Lists deliveries, newest first. Filter with `filter[endpoint]` (declared or `wh_` ids), `filter[status]`, and `filter[period]` or `filter[from]`/`filter[to]`. |
+| [`GET /api/v1/webhooks/deliveries/{deliveryId}`](/management/webhooks/retrieve-delivery) | Reads a delivery, with a `targets` entry per subscriber and one for waiting runs. |
+| [`POST /api/v1/webhooks/deliveries/{deliveryId}/replay`](/management/webhooks/replay-delivery) | Replays it, as above. The key needs permission to trigger every task the replay starts, and to write sessions if it reaches an agent's subscriber. |
+
+## Deduplication
+
+Trigger.dev uses the endpoint and idempotency key to deduplicate incoming events. Delivery records and task runs have separate deduplication windows:
+
+| What is deduplicated | Window |
+| --- | --- |
+| Delivery records | Six hours by default. |
+| Task runs | Three days for Stripe; one day for other sources. |
+
+A retry after the delivery window expires can create another delivery record. If the task-run idempotency window is still active, routing returns the existing run instead of starting another one.
+
+When the source maps a provider event ID, that ID becomes the key. For example, Stripe uses the event body's `id`, and GitHub uses the `X-GitHub-Delivery` header.
+
+If the source doesn't map an event ID, the key is derived from the raw body, timestamp, and signature. A retry with a different timestamp or signature can therefore produce a different key. For a [custom source](/webhooks/sources#custom-providers), set `idempotencyField` to a stable event identifier when the provider supplies one.
+
+## Verification and recording
+
+Requests must pass the source's verification checks before they are recorded. Timestamp checks apply when configured by the source. A verification failure returns the source's rejected HTTP status (`400` by default) and creates no delivery or run.
+
+Provider handshakes receive their configured response without creating a delivery. Other verified events are checked for duplicates, recorded, and routed. Filtered and unmatched deliveries stay visible, so you can see what arrived and why nothing ran.

package/docs/webhooks/filters.mdx

@@ -0,0 +1,109 @@
+---
+title: "Filtering deliveries"
+description: "Choose which verified webhook events reach each subscriber, by payload fields, request headers, or endpoint metadata."
+sidebarTitle: "Filters"
+---
+
+**A filter selects which verified deliveries reach a subscriber.** Each subscriber on an [endpoint](/webhooks/overview) has its own filter, so one delivery can start one task and skip another. A delivery no subscriber takes is recorded with status `FILTERED`, so you can inspect it in the dashboard.
+
+## Add a filter
+
+Set `filter` on the subscriber. This example accepts Stripe payment-intent events whose amount is at least 10,000:
+
+```ts /trigger/payment-events.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+
+export const stripe = webhooks.endpoint.define({ id: "stripe", source: webhooks.stripe() });
+
+export const largePayments = webhook({
+  id: "large-payments",
+  endpoint: stripe,
+  filter: "event.type == 'payment_intent.succeeded' && event.data.object.amount >= 10000",
+  onEvent: async ({ event }) => {
+    console.log("Matched payment event", event.id);
+  },
+});
+```
+
+The same `filter` works on a [`chat.event`](/webhooks/session-routing#filtering), a channel connector, and a [waiter](/webhooks/waiters), where it is checked after the waiter's `match`.
+
+The filter is checked against the [endpoint's event type](/webhooks/sources#typing-the-event). Concrete types catch missing fields and incompatible literals. Fields typed as `unknown`, including values in Stripe's default `data.object`, allow arbitrary non-empty field paths. Operator literals and path structure are still checked.
+
+## Check the result
+
+Send an event and open its [delivery](/webhooks/deliveries) in the dashboard. Each subscriber's row shows whether it took the event, and a filtered subscriber shows the failed clause and its value. The provider receives the source's accepted HTTP status (`200` by default) either way.
+
+<Note>
+  If filter evaluation throws an exception, Trigger.dev routes the event. Filters aren't a substitute
+  for signature verification or validation inside your handler.
+</Note>
+
+## The expression language
+
+A filter is one or more `path operator value` clauses combined with `&&` and `||` (use parentheses to group).
+
+### Paths
+
+A path reads from one of three namespaces:
+
+- `event.*`: the verified, parsed request body, for example `event.data.object.amount`.
+- `header.*`: an inbound request header, matched case-insensitively, for example `header.x-github-event`.
+- `webhook.*`: endpoint and delivery metadata: `source`, `id`, `deliveryId`, `externalRef`, and `tenantId`. The last two depend on the endpoint configuration.
+
+Paths must have non-empty segments. `event.data.amount` is valid; `event.`, `event..amount`, and `event.amount.` are rejected.
+
+[Session routing](/webhooks/session-routing) keys use the same namespaces in braces (`{event.data.object.customer}`), and [waiter](/webhooks/waiters) `match` paths use them as keys (`"event.data.object.metadata.orderId"`).
+
+### Operators
+
+| Operator | Meaning |
+| --- | --- |
+| `==` `!=` | equality |
+| `>` `<` `>=` `<=` | numeric comparison |
+| `in` `not in` | membership in a list, for example `event.type in ['a', 'b']` |
+| `startsWith` `endsWith` `contains` | string matching |
+
+Values are strings in single quotes (`'created'`), numbers (`10000`), booleans (`true`), or `null`. Use a list of these values with `in` and `not in`.
+
+### Comparing two fields
+
+Equality and comparison operators also accept a field path on the right-hand side:
+
+```text Filter expression
+event.billing.country == event.shipping.country
+```
+
+### Matching inside a list
+
+`any` matches if at least one array element meets the condition. `all` requires every element to match. The path inside the parentheses is relative to each element:
+
+```text Filter expression
+event.items any ( quantity > 0 )
+```
+
+### Spacing
+
+Separate paths, operators, and values with one space, and put spaces inside grouping and quantifier parentheses, as in `( event.amount > 0 )` and `any ( quantity > 0 )`. Lists and quoted strings may contain spaces (`['opened', 'closed']`, `'Fix the build'`). These forms work with both the TypeScript validator and the deployment parser.
+
+## Filter by event type
+
+Use the field or header your provider supplies for its event type. GitHub uses the `x-github-event` header:
+
+```ts /trigger/github-events.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+
+export const github = webhooks.endpoint.define({ id: "github", source: webhooks.github() });
+
+export const onIssuesAndPullRequests = webhook({
+  id: "github-issues-and-prs",
+  endpoint: github,
+  filter: "header.x-github-event in ['issues', 'pull_request']",
+  onEvent: async ({ headers }) => {
+    console.log("Matched GitHub event", headers.get("x-github-event"));
+  },
+});
+```
+
+## Filtering a session route
+
+A `filter` works the same way on [`chat.event`](/webhooks/session-routing): a delivery that doesn't match never reaches the session.

package/docs/webhooks/human-in-the-loop.mdx

@@ -0,0 +1,149 @@
+---
+title: "Human-in-the-loop"
+sidebarTitle: "Human-in-the-loop"
+description: "Pause an agent mid-turn to get a human decision from the channel (Slack approve/deny), then resume with the answer."
+---
+
+**An agent on a [channel](/webhooks/channels) can pause a turn to get a human decision, then resume once someone answers in the thread.** It posts controls into the conversation and picks up where it left off once someone clicks, with the decision merged into the turn. This is the channel counterpart of browser [human-in-the-loop](/ai-chat/patterns/human-in-the-loop): the same no-`execute` tool, but the controls live in Slack (or your own surface) instead of a React component. The [`slack()`](/webhooks/slack) connector ships Approve and Deny buttons out of the box.
+
+## How it works
+
+The building block is a tool with no `execute` function. When the model calls it, the turn completes with the tool call still pending instead of resolving it. Over a channel the framework then takes over the round-trip:
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant S as Slack
+    participant A as Agent run
+    U->>S: Message in a thread
+    S->>A: Verified delivery starts a turn
+    A->>A: Model calls requestApproval (no execute)
+    A->>S: renderInteraction posts Approve and Deny
+    Note over A: Turn completes, run suspends (no compute while waiting)
+    U->>S: Clicks a button
+    S->>A: Signed block_actions callback to the same webhook URL
+    A->>A: onInteraction resolves the pending tool
+    A->>S: finalizeInteraction collapses the buttons
+    A->>A: Run resumes, model continues
+    A->>S: Reply posts back to the thread
+```
+
+Because it is a no-`execute` pause, the run suspends while it waits rather than holding compute. A human can take minutes or days to decide without burning compute or hitting [`maxDuration`](/runs/max-duration). The mechanics are the same as the browser case, covered in [human-in-the-loop](/ai-chat/patterns/human-in-the-loop#duration-and-cost-while-paused).
+
+## Slack approvals
+
+Out of the box, `slack()` posts Approve and Deny buttons for any pending no-`execute` tool. A click resolves to `{ approved: boolean }` and the buttons collapse to the decision. You define the tool and list the channel on the agent:
+
+```ts trigger/support-agent.ts
+import { webhooks } from "@trigger.dev/sdk";
+import { chat } from "@trigger.dev/sdk/ai";
+import { slack, webhookSource } from "@trigger.dev/slack";
+import { tool } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
+import { z } from "zod";
+
+const slackEvents = webhooks.endpoint.define({ id: "slack", source: webhookSource() });
+
+// No execute: calling this pauses the turn for a human decision.
+const requestApproval = tool({
+  description:
+    "Request human approval before a sensitive or irreversible action. " +
+    "Call this and stop; you will receive { approved: boolean }, then proceed or decline.",
+  inputSchema: z.object({
+    action: z.string().describe("A short description of the action needing approval"),
+  }),
+});
+
+export const supportAgent = chat.agent({
+  id: "support-agent",
+  channels: [slack({ id: "support-slack", endpoint: slackEvents, token: process.env.SLACK_BOT_TOKEN! })],
+  tools: { requestApproval },
+  run: async ({ messages, tools, streamText }) =>
+    streamText({
+      model: anthropic("claude-sonnet-4-5"),
+      messages,
+      tools,
+      system:
+        "Before any sensitive or irreversible action (refunds, cancellations, deletions), " +
+        "call requestApproval and wait. If approved, confirm it is done; if denied, decline.",
+    }),
+});
+```
+
+Button clicks arrive through Slack's interactivity, so the app needs **Interactivity & Shortcuts** turned on with the Request URL set to the **same** endpoint URL as events. The [Slack agents](/webhooks/slack#setup) manifest already does this.
+
+When the model calls `requestApproval`, the bot posts "Approval needed" with the action and Approve and Deny buttons, and the session's status is **suspended**. Clicking **Approve** resolves the tool to `{ approved: true }`, the buttons collapse to "Approved by @you", and the agent continues and streams the outcome. **Deny** resolves `{ approved: false }`. Pressing Slack's stop button instead cancels the approval: the buttons are replaced with "Stopped" and a later click resumes nothing.
+
+## Customizing the controls
+
+For [`chat.channels.custom`](/webhooks/channels), four hooks own the interaction round-trip:
+
+<ParamField body="renderInteraction" type="(pending, ctx) => ChannelMessage | null">
+  Map the pending tool call(s) to the controls you post. `pending` is a list of `{ toolCallId, toolName, input }`, and `ctx` carries the `event` and `deliveryId` that started the turn (both absent on a bound turn, such as a `chat.turn()` action answering into the thread). Return `null` to skip posting controls.
+</ParamField>
+
+<ParamField body="onInteraction" type="(event) => { toolCallId, output } | null">
+  Map a verified callback event to a resolution. The `output` is stitched onto the pending tool call matched by `toolCallId` and the run resumes. Return `null` to treat the event as a normal message instead (a new turn).
+</ParamField>
+
+<ParamField body="finalizeInteraction" type="(event, resolution) => void">
+  Collapse the controls after a decision so they cannot be clicked again. Best effort: a failure here is logged and the run still resumes.
+</ParamField>
+
+<ParamField body="cancelInteraction" type="(cancelled, ctx) => void">
+  Take the controls down when a stop (`onControl` returning `{ kind: "stop", whenIdle: "drop" }`) arrives while the session waits on them. Each cancelled call carries the `ref` its controls were posted with. The calls are already resolved as stopped. Best effort: a failure is logged.
+</ParamField>
+
+Slack encodes the tool call id and the click's output in each button's `value` so `onInteraction` can resolve the exact call (see [Approvals and buttons](/webhooks/slack#approvals-and-buttons) to customize the buttons or give a tool its own UI), and `finalizeInteraction` posts to the interaction's `response_url` with `replace_original` to swap the buttons for the outcome. On a custom surface you choose the encoding and how you edit the controls away.
+
+```ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { webhooks } from "@trigger.dev/sdk";
+
+const surface = webhooks.endpoint.define({
+  id: "my-surface",
+  source: webhooks.custom<MyEvent>({ /* verifier config */ }),
+});
+
+chat.channels.custom({
+  id: "my-surface",
+  endpoint: surface,
+  key: "{event.conversationId}",
+  inbound: (e) => e.text,
+  send: async (message, ctx) => ({ ref: await postToMySurface(ctx.event, message) }),
+  renderInteraction: (pending) => ({
+    text: `Approve: ${pending[0].input.action}?`,
+    buttons: pending.map((c) => [`${c.toolCallId}:yes`, `${c.toolCallId}:no`]),
+  }),
+  onInteraction: (e) => {
+    const [toolCallId, choice] = e.buttonValue.split(":");
+    return { toolCallId, output: { approved: choice === "yes" } };
+  },
+  finalizeInteraction: async (e) => {
+    await editMySurface(e.messageRef, "Decision recorded");
+  },
+});
+```
+
+The resolved `output` is whatever your tool expects to receive. The Slack default resolves `{ approved: boolean }`; if your tool needs a richer answer, supply your own `onInteraction` that returns the shape your tool reads.
+
+## The reply after a decision
+
+When the turn resumes, the channel reply shows the agent's answer, not the text it produced before pausing. The framework posts the assistant text generated after the tool call, so a preamble like "I'll need approval first" is not concatenated onto the final "done" message. The approval prompt itself already lives in the collapsed controls.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Channels" icon="comments" href="/webhooks/channels">
+    Point Slack or any surface at an agent so messages become turns.
+  </Card>
+  <Card title="Browser human-in-the-loop" icon="hand" href="/ai-chat/patterns/human-in-the-loop">
+    The same no-execute pause, rendered in a React frontend.
+  </Card>
+  <Card title="Sessions" icon="layer-group" href="/ai-chat/sessions">
+    The durable per-conversation state a channel turn runs on.
+  </Card>
+  <Card title="Filters" icon="filter" href="/webhooks/filters">
+    Gate which verified deliveries reach the agent.
+  </Card>
+</CardGroup>

package/docs/webhooks/linear.mdx

@@ -0,0 +1,185 @@
+---
+title: "Linear agents"
+description: "Turn a chat.agent into a Linear agent: assign it an issue or @mention it, and it works the issue inside Linear's agent session UI."
+sidebarTitle: "Linear agents"
+---
+
+Linear opens an **agent session** when someone @mentions your app in an issue or delegates (assigns) an issue to it. `linear()` from `@trigger.dev/linear` is a [channel](/webhooks/channels) connector for those sessions: each one becomes a durable Trigger.dev [session](/ai-chat/sessions), the user's prompt runs as a turn, and the agent's work shows up in Linear as thoughts, actions, a plan, an approval card when it needs a decision, and a response when it is done.
+
+```ts
+import { webhooks } from "@trigger.dev/sdk";
+import { chat } from "@trigger.dev/sdk/ai";
+import { linear, webhookSource } from "@trigger.dev/linear";
+import { anthropic } from "@ai-sdk/anthropic";
+
+const linearEvents = webhooks.endpoint.define({ id: "linear", source: webhookSource() });
+
+export const triage = chat.agent({
+  id: "triage",
+  channels: [linear({ id: "linear", endpoint: linearEvents, token: process.env.LINEAR_ACCESS_TOKEN! })],
+  tools: { searchDocs, createSubIssues },
+  run: async ({ messages, tools, signal, streamText }) =>
+    streamText({ model: anthropic("claude-sonnet-4-5"), messages, tools, abortSignal: signal }),
+});
+```
+
+The `run()` loop is the same one a browser chat or a Slack thread uses. Verification, the five second webhook acknowledgment, the first activity Linear expects within ten seconds, per-session state, dedup of Linear's retries, replay and the transcript are handled for you.
+
+## Setup
+
+<Steps>
+  <Step title="Create the OAuth app">
+    In Linear, create an OAuth application under **Settings, API**. Enable **Webhooks** on it and turn on the **Agent session events** category (Inbox notifications and Permission changes are useful too). Copy the webhook **signing secret**.
+  </Step>
+  <Step title="Install it as an agent">
+    Authorize the app with `actor=app` in the authorization URL and request the `app:assignable` and `app:mentionable` scopes, so members can assign issues to it and @mention it. Installation needs a workspace admin. Keep the resulting access token; pass it as `token`.
+  </Step>
+  <Step title="Deploy and connect the endpoint">
+    Declare the endpoint with `webhookSource()` from `@trigger.dev/linear` and pass it to `linear({ endpoint })`. Deploying registers the hosted [endpoint](/webhooks/connect). Paste the app's webhook signing secret as the endpoint's signing secret, and set the app's webhook URL to the endpoint's URL. The endpoint's setup prompt walks an AI coding agent through these settings.
+  </Step>
+  <Step title="Try it">
+    Open an issue and assign it to the app, or write a comment that @mentions it. Linear shows the agent's first thought within a few seconds and then its work.
+  </Step>
+</Steps>
+
+## What the agent sees
+
+On the first turn of a session the connector frames Linear's payload for the model: who summoned it and on which issue, the workspace **guidance** rules for agents, Linear's formatted **issue context** (title, description, labels, project, comments), and the comment that mentioned it. An assignment with no comment reads as "assigned ENG-412 to you". Prior comments on the issue are [seeded](/webhooks/channels#joining-a-thread-that-already-has-messages) as transcript messages, so the agent can answer with the context a reader of the issue has.
+
+A follow-up prompt on the session is just the message. If the user hits **Stop** in Linear, see [Stopping](#stopping).
+
+Images and PDFs uploaded to Linear reach the model as files: screenshots in the prompt, in the comment that mentioned the agent, or in the issue description. The transcript keeps the upload link, and the `streamText` passed to `run()` downloads the file with the app's token when the model reads it, at most ten per message. A file that can't be downloaded reaches the model as a short note. A custom `inbound` keeps this by adding `linearFileParts(markdown)` to its message parts.
+
+Turn any of that off with `context`:
+
+```ts
+linear({ id: "linear", endpoint: linearEvents, token, context: { guidance: false, promptContext: true, previousComments: true } })
+```
+
+## What Linear shows
+
+| Moment | Activity in Linear |
+| --- | --- |
+| Turn starts | An ephemeral `thought` ("Looking into this...") |
+| A tool is called | An ephemeral `action` with the tool name and input, then the same action with its `result` |
+| The reply is ready | A `response` with the reply as markdown |
+| The turn fails | An `error` |
+| A tool needs a human decision | An `elicitation` with Approve and Deny options, or the tool's own options from `interactions` (see [Approvals and choices](#approvals-and-choices)) |
+| The user picks an option | A `thought` recording the decision ("Approved by Jane.", "Jane chose "High".") |
+| A prompt arrives while the agent works | A `thought` ("Got it, I'll take that into account.") as soon as it arrives (see [Prompts sent while the agent is working](#prompts-sent-while-the-agent-is-working)) |
+
+Tool mirroring is on by default; pass `progress: "off"` to post only the response. Bare Linear URLs in a reply become mentions, so link issues and documents by URL.
+
+## The plan
+
+Linear shows an agent's plan as a checklist under the conversation. The model owns it: add `linearPlanTool()` to the agent's tools and ask for a plan in the system prompt, and the model sets it when it starts and updates it as steps finish. The whole list is replaced on each call. On a turn that is not a Linear session the tool reports that nothing was updated, so `run()` needs no Linear-specific code.
+
+```ts
+import { linear, linearPlanTool } from "@trigger.dev/linear";
+
+export const triage = chat.agent({
+  id: "triage",
+  channels: [linear({ id: "linear", endpoint: linearEvents, token })],
+  tools: { searchDocs, createSubIssues, updatePlan: linearPlanTool() },
+  run: async ({ messages, tools, signal, streamText }) =>
+    streamText({
+      model,
+      messages,
+      tools,
+      abortSignal: signal,
+      system: "Start by setting a short plan with updatePlan and keep it current as you work.",
+    }),
+});
+```
+
+## Helpers
+
+For manual control, `chat.surface<LinearRunSurface>()` returns the current turn's helpers from anywhere inside the run, including a tool's `execute`. The same object is handed to `run()` as `channel`.
+
+| Helper | Effect |
+| --- | --- |
+| `plan(steps)` | Replace the session's plan. Each step is `{ content, status }` with status `pending`, `inProgress`, `completed` or `canceled`. What `linearPlanTool()` calls. |
+| `thought(text, { ephemeral })` | Post a thought. |
+| `action(action, parameter, result?)` | Post an action, optionally with its result. |
+| `link(label, url)` | Add an external link to the session header (a pull request, a dashboard). |
+| `summary(text)` | Set the one-line session summary. |
+| `session` | The bound agent session and issue ids. |
+
+## Approvals and choices
+
+A tool with no `execute` pauses the turn for a human decision, exactly as on [any channel](/webhooks/human-in-the-loop). On Linear the connector posts an elicitation card with Approve and Deny options. The card lays the tool input out as markdown: a list of proposed items becomes a numbered list with a bold title per item, a flat object becomes key and value bullets, and only shapes it cannot lay out fall back to JSON. For a card written for the tool, pass a renderer per tool name:
+
+```ts
+linear({
+  id: "linear",
+  endpoint: linearEvents,
+  token,
+  approvals: {
+    createSubIssues: (input) => ({
+      title: "Create these sub-issues?",
+      body: (input as { issues: { title: string }[] }).issues.map((i) => `- ${i.title}`).join("\n"),
+    }),
+  },
+})
+```
+
+The user picks one and presses Continue; the choice shows in the session as "Approve createSubIssues [call_a]" (the tool and the call it applies to, so the decision always lands on the call whose input the card shows) and resumes the run with `{ approved: true | false }`, and the decision is recorded as a thought. Typing a free-text reply instead dismisses the options and runs as a normal turn, so the model can take the reply into account (and ask again) with the approval still pending.
+
+`interactions` gives a tool its own choices instead of Approve and Deny. The card is a select of `options`, and the chosen option resolves the tool to `{ selected }`:
+
+```ts
+linear({
+  id: "linear",
+  endpoint: linearEvents,
+  token,
+  interactions: {
+    pickPriority: (call) => ({
+      title: "What priority should this be?",
+      body: (call.input as { reason: string }).reason,
+      options: ["Urgent", "High", "Medium", "Low"],
+    }),
+  },
+})
+```
+
+The choice shows in the session as "High [choice:call_a]", resumes the run with `{ selected: "High" }`, and is recorded as a thought.
+
+## Stopping
+
+Pressing Stop in Linear sends the session a prompt with the `stop` signal. While a turn is running, the connector aborts it through the agent's stop signal (the same one the browser's stop button uses): generation halts, the text written so far posts as the response with `stopped: true`, and the stop prompt itself is consumed. Pressed while the agent is idle, the prompt runs as a turn that tells the model to stop taking actions and summarize. A Stop pressed while a turn was running that arrives after the turn finished is consumed, so pressing Stop twice never adds a wind-down turn.
+
+## Prompts sent while the agent is working
+
+A prompt sent while the agent is still working gets a thought as soon as it arrives ("Got it, I'll take that into account."), so the user knows it was picked up. It then waits and runs as the next turn. With [`pendingMessages`](/ai-chat/pending-messages) on the agent, `shouldInject` can fold it into the work in progress at the next step instead; a prompt it declines still runs as its own turn. `receivedThought` changes the text, takes a function of the event for wording per prompt, and `null` posts nothing; since the prompt may be answered either way, keep the wording true for both. Stop and the approval card's options are never acknowledged or folded in.
+
+## Answering into the session from elsewhere
+
+The first Linear turn binds the session to the agent session ([bound sessions](/webhooks/channels#bound-sessions)). A [`chat.event`](/webhooks/session-routing) routed to the same session key, a Sentry alert keyed on the issue identifier for example, can return `chat.turn()` from `onAction` and its answer posts into the Linear session as a response, with no Linear event involved. Linear reopens a completed session when new activity arrives.
+
+## Options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Connector id, unique per agent. |
+| `endpoint` | endpoint | The Linear endpoint, declared with `webhooks.endpoint.define({ id, source: webhookSource() })`. Other `webhook()` tasks can subscribe to the same endpoint. |
+| `token` | `string` or resolver | The app's OAuth access token, or a function of the event (keyed on `organizationId`) for multi-workspace installs. |
+| `key` | `string` | Session [key](/webhooks/session-routing) template over `{event.*}`, `{header.*}` and `{webhook.*}`. Defaults to one session per Linear agent session. |
+| `filter` | `string` | Extra [filter](/webhooks/filters), composed with the built-in agent-session guard. |
+| `startOn` | `string` | Only start a session when the event matches. Existing sessions always resume. |
+| `context` | `{ guidance?, promptContext?, previousComments? }` | What from Linear's payload is put in front of the model on the first turn. All on by default. |
+| `progress` | `"actions"` or `"off"` | Mirror tool calls as action activities (default) or post only the response. |
+| `summarize` | `boolean` | Set the session title from each response's first line. Off by default; Linear titles the session itself. |
+| `approvals` | `{ [toolName]: (input, call) => { title?, body } }` | Custom approval card body per tool. Default lays the tool input out as markdown. |
+| `interactions` | `{ [toolName]: (call) => { title?, body, options } }` | A tool's own select card; the chosen option resolves the tool to `{ selected }`. |
+| `receivedThought` | `string`, function or `null` | Thought posted as soon as a prompt arrives while the agent is working. Default "Got it, I'll take that into account.", null for none. |
+| `ack` | message, `null`, or function | The first thought. Pass `null` to post nothing before the response. |
+| `inbound` / `outbound` | functions | Map the event to the turn, and the reply to an activity. |
+| `delivery` | `"final"` or `"stream"` | `"final"` (default) posts the response when the turn ends. `"stream"` also posts ephemeral thoughts as the reply streams. |
+| `apiUrl` | `string` | Override the Linear GraphQL URL, for testing against a mock. Files on its origin are treated as Linear uploads. |
+
+<Note>
+  Linear expects the first activity within ten seconds of opening a session. The connector posts it at
+  the top of the run, so on a cold start close to that limit the session can show as unresponsive for a
+  moment; it recovers as soon as the thought lands. Linear retries a failed delivery after one minute,
+  one hour and six hours, and the endpoint deduplicates those retries.
+</Note>

package/docs/webhooks/overview.mdx

@@ -0,0 +1,99 @@
+---
+title: "Webhooks overview"
+description: "Receive provider webhooks on hosted, verified endpoints and route each event to tasks, agents, and waiting runs."
+sidebarTitle: "Overview"
+---
+
+**A webhook endpoint is one hosted URL that you register with a provider.** Trigger.dev verifies every request against the endpoint's [source](/webhooks/sources), records it as a [delivery](/webhooks/deliveries), and hands the event to everything subscribed to the endpoint.
+
+Declare the endpoint once, then subscribe to it:
+
+```ts /trigger/stripe.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+
+export const stripe = webhooks.endpoint.define({
+  id: "stripe",
+  source: webhooks.stripe(),
+});
+
+export const fulfillOrder = webhook({
+  id: "fulfill-order",
+  endpoint: stripe,
+  filter: "event.type == 'checkout.session.completed'",
+  onEvent: async ({ event }) => {
+    console.log("Fulfilling", event.data.object.id);
+  },
+});
+
+export const recordRefund = webhook({
+  id: "record-refund",
+  endpoint: stripe,
+  filter: "event.type == 'charge.refunded'",
+  onEvent: async ({ event, headers, endpoint, ctx }) => {
+    console.log("Refund", event.id, "on", endpoint?.id, "in run", ctx.run.id);
+  },
+});
+```
+
+Stripe gets one URL. A checkout event runs `fulfill-order`, a refund runs `record-refund`, and anything else is recorded as `FILTERED`.
+
+## What can subscribe
+
+| Subscriber | Declared with | What a delivery does |
+| --- | --- | --- |
+| Task | `webhook({ endpoint, onEvent })` | Starts a run of the task with the event. |
+| Agent session | [`chat.event({ endpoint, key })`](/webhooks/session-routing) listed on a `chat.agent` | Delivers an action to the session the `key` names. |
+| Chat frontend | a [channel connector](/webhooks/channels) such as `chat.channels.custom({ endpoint })` | Runs a turn on the conversation's session and posts the reply back. |
+| Waiting run | [`webhooks.waiter.create(endpoint, { match })`](/webhooks/waiters) | Resumes a run that is waiting for this event. |
+
+Each subscriber has its own [filter](/webhooks/filters), so one delivery can reach several subscribers and skip the rest. An endpoint can have up to 25 subscribers. An endpoint with no subscribers still gets a URL, so you can register it with the provider before writing the handlers.
+
+## The handler
+
+`onEvent` receives:
+
+| Argument | Value |
+| --- | --- |
+| `event` | The verified request body, parsed as JSON. Its TypeScript type comes from the [source](/webhooks/sources#typing-the-event). |
+| `headers` | Request headers as a Web `Headers` object, with case-insensitive `get()` and `has()` methods. Credentials such as signatures are removed. |
+| `endpoint` | The endpoint the delivery arrived on: `id`, `declaredId`, `tenantId`, `externalRef`, and the `metadata` you declared. |
+| `ctx` | The same [run context](/context) that regular tasks receive. |
+
+`webhooks.endpoint.define` also takes a `description` and `metadata`. The metadata is passed to every subscriber as `endpoint.metadata`. The endpoint `id` can't start with `wh_`, which is reserved for the ids Trigger.dev generates.
+
+## How it works
+
+The CLI finds your endpoints and subscribers during `trigger dev` and deployment, and each environment gets one endpoint per declared id. The endpoint holds the URL and the credential used to verify requests.
+
+A request must pass verification before anything else happens. Provider handshakes are answered directly and create no delivery. A verified request is checked for duplicates, recorded, and then routed: each subscriber's filter is checked, matching subscribers run, and waiting runs whose match fits the event are resumed. The delivery records a result per subscriber.
+
+## Connect it
+
+Every endpoint can produce a setup prompt for an AI coding agent. It holds the URL, the events your subscribers filter on, and the steps for registering the endpoint and its signing secret with the provider. Copy it from the endpoints list or the endpoint's page, or read it with the MCP server's `get_webhook_endpoint_details` tool. See [Connect a provider](/webhooks/connect).
+
+<CardGroup cols={2}>
+  <Card title="Connect a provider" icon="plug" href="/webhooks/connect">
+    Register the URL and signing secret, then send a test event.
+  </Card>
+  <Card title="Sources and verification" icon="shield-check" href="/webhooks/sources">
+    Choose a provider source or define a custom verification scheme.
+  </Card>
+  <Card title="Filters" icon="filter" href="/webhooks/filters">
+    Choose which events reach each subscriber.
+  </Card>
+  <Card title="Waiters" icon="hourglass" href="/webhooks/waiters">
+    Pause a run until a matching webhook arrives.
+  </Card>
+  <Card title="Deliveries and endpoints" icon="inbox" href="/webhooks/deliveries">
+    Inspect received events and where each one went.
+  </Card>
+  <Card title="Session routing" icon="arrows-to-dot" href="/webhooks/session-routing">
+    Route deliveries to a durable per-key agent session.
+  </Card>
+  <Card title="Channels" icon="comments" href="/webhooks/channels">
+    Turn a webhook into a chat frontend for an agent.
+  </Card>
+  <Card title="Human-in-the-loop" icon="user-check" href="/webhooks/human-in-the-loop">
+    Approvals and interactive controls over a channel.
+  </Card>
+</CardGroup>