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

package/docs/deployment/atomic-deployment.mdx

@@ -60,7 +60,7 @@ The id is free-form and opaque to Trigger.dev — a commit SHA, a release tag, a
 <Step title="Deploy your tasks with an external id">
 
 ```bash
-npx trigger.dev@latest deploy --external-id "$(git rev-parse HEAD)"
+npx trigger.dev@latest deploy --env prod --external-id "$(git rev-parse HEAD)"
 ```
 
 </Step>
@@ -240,7 +240,7 @@ Read the commit in the place where it *is* available, and write it into both hal
 
 ```bash
 # 1. Deploy side — name the deployment after the commit.
-npx trigger.dev@latest deploy --external-id "$(git rev-parse HEAD)"
+npx trigger.dev@latest deploy --env prod --external-id "$(git rev-parse HEAD)"
 
 # 2. Application side — give the running app the same value.
 TRIGGER_EXTERNAL_DEPLOYMENT_ID=<the-same-commit-sha>
@@ -385,7 +385,7 @@ If you filter deploys by path, derive the id from the same filter on both sides
 
 ```bash
 TASK_ID=$(git log -1 --format=%H -- trigger/)
-npx trigger.dev@latest deploy --external-id "$TASK_ID"
+npx trigger.dev@latest deploy --env prod --external-id "$TASK_ID"
 ```
 
 Compute the same value where you set your app's variable. In GitHub Actions this needs `fetch-depth: 0` on `actions/checkout` — the default shallow clone can't see far enough back.

package/docs/deployment/overview.mdx

@@ -162,7 +162,7 @@ To keep your app and tasks in sync without coordinating promotion at all, see [a
 
 ## Staging deploys
 
-By default, the `deploy` command will deploy to the `prod` environment. If you want to deploy to a different environment, you can use the `--env` flag:
+Use the `--env` flag to choose the environment you deploy to. If you don't pass it, the `deploy` command deploys to the `prod` environment, unless `TRIGGER_ACCESS_TOKEN` holds an API key for another environment. To deploy to staging:
 
 ```bash
 npx trigger.dev deploy --env staging

package/docs/deployment/preview-branches.mdx

@@ -147,7 +147,7 @@ Creating and deploying a preview branch manually is easy:
 npx trigger.dev@latest deploy --env preview
 ```
 
-This will create and deploy a preview branch, automatically detecting the git branch. If for some reason the auto-detection doesn't work it will let you know and tell you do this:
+This will create and deploy a preview branch, automatically detecting the git branch. When your CI checks out a detached HEAD, the branch is read from the CI provider's branch variable instead (GitLab, Bitbucket, CircleCI, Buildkite, Travis CI, Jenkins and Azure Pipelines are supported). If for some reason the auto-detection doesn't work it will let you know and tell you do this:
 
 ```bash
 npx trigger.dev@latest deploy --env preview --branch your-branch-name

package/docs/github-actions.mdx

@@ -47,7 +47,7 @@ jobs:
         env:
           TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
         run: |
-          npx trigger.dev@latest deploy --external-id ${{ github.sha }}
+          npx trigger.dev@latest deploy --env prod --external-id ${{ github.sha }}
 ```
 
 ```yaml .github/workflows/release-trigger-staging.yml
@@ -184,7 +184,7 @@ Tip: add the `trigger.dev` CLI to your `devDependencies` and the deploy command
 ```json
 {
   "scripts": {
-    "deploy:trigger-prod": "trigger deploy",
+    "deploy:trigger-prod": "trigger deploy --env prod",
     "deploy:trigger": "trigger deploy --env staging"
   },
   "devDependencies": {
@@ -254,7 +254,7 @@ jobs:
           TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
           TRIGGER_API_URL: ${{ secrets.TRIGGER_API_URL }}
         run: |
-          npx trigger.dev@latest deploy
+          npx trigger.dev@latest deploy --env prod
 ```
 
 </CodeGroup>

package/docs/limits.mdx

@@ -12,6 +12,12 @@ You can view your current limits, quotas, and rate limit usage in real-time by v
   [Billing limits and alerts](/billing-limits).
 </Note>
 
+## Run duration
+
+Runs have no maximum duration. You set a default `maxDuration` for your project and can override it per task or per run, or set it to `timeout.None` to let a run execute indefinitely.
+
+Trigger is built for long running AI agents and workflows and we have seen Trigger.dev users with runs lasting more than six months.
+
 ## Concurrency limits
 
 Concurrency is allocated **per environment**, not as a single figure for the whole organization. Each plan sets a separate default for production, staging, preview and development:

package/docs/manual-setup.mdx

@@ -109,7 +109,7 @@ Then add scripts to your `package.json`:
 {
   "scripts": {
     "dev:trigger": "trigger dev",
-    "deploy:trigger": "trigger deploy"
+    "deploy:trigger": "trigger deploy --env prod"
   }
 }
 ```

package/docs/mcp-tools.mdx

@@ -189,7 +189,7 @@ Execute a TRQL query against your Trigger.dev data. TRQL is a SQL-style query la
 
 ### list_dashboards
 
-List available built-in dashboards with their widgets. Each dashboard contains pre-built queries for common metrics.
+List the built-in dashboards and your organization's custom dashboards, with their widgets.
 
 **Example usage:**
 - `"What dashboards are available?"`
@@ -197,12 +197,28 @@ List available built-in dashboards with their widgets. Each dashboard contains p
 
 ### run_dashboard_query
 
-Execute a single widget query from a built-in dashboard. Use `list_dashboards` first to see available dashboards and widget IDs.
+Execute a single widget query from a built-in or custom dashboard. Use `list_dashboards` first to see available dashboards and widget IDs.
 
 **Example usage:**
 - `"Run the total runs widget from the overview dashboard"`
 - `"Show me the LLM cost over time from the AI dashboard"`
 
+### create_dashboard
+
+Create a custom dashboard, optionally with widgets. Each widget has a title, a TRQL query and a display: a table, a bar or line chart, a big number, or a section title. Queries are checked when the dashboard is saved.
+
+**Example usage:**
+- `"Make a dashboard for the email tasks with total runs, failures and runs per day"`
+- `"Create a dashboard that charts p95 duration by task"`
+
+### set_dashboard_widgets
+
+Replace every widget on a custom dashboard, and optionally rename it.
+
+**Example usage:**
+- `"Add a failed runs widget to the email dashboard"`
+- `"Change the runs per day chart to a line chart"`
+
 ### get_report
 
 Render an interpreted [health report](/reports) — a deterministic verdict, not a raw panel — as text with sparklines. The `health` report answers whether work is flowing, whether the runs that start are healthy, and whether the telemetry is fresh, with a headline verdict and a suggested next action. Returns markdown by default, or ANSI when `color` is set. Read-only.
@@ -239,7 +255,7 @@ Check the status of the dev server and view recent output. Shows whether it is s
 - `"Are there any build errors?"`
 
 <Callout type="warning">
-  The deploy and list_preview_branches tools are not available when the MCP server is running with the `--dev-only` flag. The `--readonly` flag hides deploy, trigger_task, cancel_run, and replay_run.
+  The deploy and list_preview_branches tools are not available when the MCP server is running with the `--dev-only` flag. The `--readonly` flag hides deploy, trigger_task, cancel_run, replay_run, create_dashboard, and set_dashboard_widgets.
 </Callout>
 
 ## Agent Chat Tools

package/docs/observability/dashboards.mdx

@@ -45,6 +45,68 @@ You can also filter the data by:
 4. For charts you write [TRQL queries](/observability/query) and choose a visualization type.
 5. You can resize and reposition widgets on your dashboards.
 
+## Managing dashboards with the SDK
+
+Custom dashboards can also be created and edited from code, so you can keep them in your repository and set them up from CI or a script. `query.dashboards` covers the same operations as the dashboard UI.
+
+```ts scripts/dashboards.ts
+import { query } from "@trigger.dev/sdk";
+
+const dashboard = await query.dashboards.create({
+  title: "Email tasks",
+  widgets: [
+    { title: "Overview", display: { type: "title" } },
+    {
+      title: "Total runs",
+      query: "SELECT count() AS total FROM runs WHERE task_identifier = 'send-email'",
+      display: { type: "bignumber", column: "total", aggregation: "sum" },
+    },
+    {
+      title: "Runs per day",
+      query:
+        "SELECT timeBucket(), count() AS runs FROM runs WHERE task_identifier = 'send-email' GROUP BY timeBucket ORDER BY timeBucket",
+      display: {
+        type: "chart",
+        chartType: "bar",
+        xAxisColumn: "timebucket",
+        yAxisColumns: ["runs"],
+        groupByColumn: null,
+        stacked: false,
+        sortByColumn: null,
+        sortDirection: "asc",
+        aggregation: "sum",
+      },
+    },
+  ],
+});
+
+console.log(dashboard.id); // dashboard_...
+```
+
+Widgets without a `position` are stacked full width in the order you list them. Pass `position: { x, y, w, h }` on a 12-column grid to place a widget yourself.
+
+To keep a dashboard in sync with code, replace all of its widgets in one call. Widgets you keep, matched by `id`, stay where they are unless you pass a new `position`:
+
+```ts scripts/dashboards.ts
+const current = await query.dashboards.retrieve(dashboard.id);
+
+await query.dashboards.replace(dashboard.id, {
+  widgets: [
+    {
+      id: "failures",
+      title: "Failed runs",
+      query: "SELECT count() AS failed FROM runs WHERE status = 'Failed'",
+      display: { type: "bignumber", column: "failed", aggregation: "sum" },
+    },
+  ],
+  revision: current.revision,
+});
+```
+
+`revision` is optional. When you pass the revision you last read, the write fails with a 409 if someone changed the dashboard in the meantime, instead of overwriting their change.
+
+Every widget query is checked against the queryable tables when you save it, so a typo in a table or column name fails the request with the list of valid columns. `query.dashboards.widgets.add`, `widgets.update` and `widgets.del` change one widget at a time. Creating a dashboard or widget past your plan's limits returns a 403. See the [Query API reference](/management/query/create-dashboard) for every endpoint.
+
 ## Performance considerations
 
 ### Optimize queries for metrics

package/docs/runs/max-duration.mdx

@@ -4,6 +4,10 @@ sidebarTitle: "Max duration"
 description: "Set a maximum duration for a task to run."
 ---
 
+Runs have no maximum duration. You set a default `maxDuration` for your project and can override it per task or per run, or set it to `timeout.None` to let a run execute indefinitely.
+
+Trigger is built for long running AI agents and workflows and we have seen Trigger.dev users with runs lasting more than six months.
+
 The `maxDuration` parameter sets a maximum compute time limit for tasks. When a task exceeds this duration, it will be automatically stopped. This helps prevent runaway tasks and manage compute resources effectively.
 
 You must set a default maxDuration in your `trigger.config.ts` file, which will apply to all tasks unless overridden:

package/docs/self-hosting/env/supervisor.mdx

@@ -65,6 +65,7 @@ mode: "wide"
 | `FAILED_POD_HANDLER_ENABLED`                | No       | true        | Enable failed pod handler.                                  |
 | `FAILED_POD_HANDLER_RECONNECT_INTERVAL_MS`  | No       | 1000 (1s)   | Failed pod handler reconnect interval (ms).                 |
 | `FAILED_POD_HANDLER_WATCH_TIMEOUT_SECONDS`  | No       | 300 (5m)    | How long the server keeps each failed pod watch open (s).   |
+| `RUNNER_KILL_REPORTS_ENABLED`               | No       | true        | Fail a run straight away when its pod is killed, as out of memory only if Kubernetes reports `OOMKilled`. |
 | **Debug**                                   |          |             |                                                             |
 | `DEBUG`                                     | No       | false       | Enable debug logs.                                          |
 | `SEND_RUN_DEBUG_LOGS`                       | No       | false       | Send run debug logs to the platform.                        |

package/docs/webhooks/channels.mdx

@@ -11,14 +11,21 @@ List channels on a [`chat.agent`](/ai-chat/overview) alongside (or instead of) `
 ```ts
 import { webhooks } from "@trigger.dev/sdk";
 import { chat } from "@trigger.dev/sdk/ai";
-import { slack, webhookSource } from "@trigger.dev/slack";
+import { appMentions, slack, webhookSource } from "@trigger.dev/slack";
 import { anthropic } from "@ai-sdk/anthropic";
 
 const slackEvents = webhooks.endpoint.define({ id: "slack", source: webhookSource() });
 
 export const supportAgent = chat.agent({
   id: "support-agent",
-  channels: [slack({ id: "support-slack", endpoint: slackEvents, token: process.env.SLACK_BOT_TOKEN! })],
+  channels: [
+    slack({
+      id: "support-slack",
+      endpoint: slackEvents,
+      token: process.env.SLACK_BOT_TOKEN!,
+      startOn: appMentions(),
+    }),
+  ],
   run: async ({ messages, streamText }) =>
     streamText({ model: anthropic("claude-sonnet-4-5"), messages }),
 });
@@ -59,17 +66,36 @@ const mySurface = chat.channels.custom({
   outbound: (reply) => (reply.text ? { text: reply.text } : null), // null posts nothing
   send: async (message, ctx) => {
     const ref = await postToMySurface(ctx.event, message.text, ctx.previousRef);
-    return { ref }; // an existing ref means edit-in-place on the next turn
+    return { ref }; // later sends in the same turn get it back as ctx.previousRef
   },
 });
 ```
 
-`send` is called to post the reply. `ctx.previousRef` is the ref you returned last time, so streaming or a follow-up edits the same message instead of posting a new one. Return `null` from `outbound` to stay silent (a tool-only turn, say).
+`send` is called to post the reply. Within a turn, `ctx.previousRef` is the ref you returned from the turn's earlier `send` (the acknowledgement, or the message being streamed), so later sends edit that message instead of posting a new one. Each turn starts without a ref: the next turn's answer is a new message. Return `null` from `outbound` to stay silent (a tool-only turn, say).
 
 An event that `inbound` maps to an empty message (no text, and no file or data parts) runs no turn. A click or system event your surface sends to the same endpoint is dropped rather than answered with an empty prompt.
 
 List the connector in `chat.agent({ channels: [mySurface] })`, which subscribes the agent to the endpoint with the id `agentId:connectorId`. Other subscribers on the endpoint keep receiving its deliveries.
 
+## When a turn fails
+
+When a turn fails (the model or provider returns an error, or the turn throws), the channel shows a short line instead of the error: "Something went wrong answering this. Try again." by default, or the connector's `errorMessage`. If the reply had partly streamed, the line goes after that text. The error is logged on the run, and `outbound` receives it as `reply.error`, so you can render a failure differently.
+
+`errorMessage` is a fixed string, or a function that builds the line from the failure. It receives the `error`, the `partialText` streamed before it failed, the triggering `event` (undefined on a turn the channel didn't start), the `runId`, the `chatId`, and the `defaultMessage`. Return nothing, or throw, to fall back to the default line.
+
+```ts
+slack({
+  id: "slack",
+  endpoint: slackEvents,
+  token: process.env.SLACK_BOT_TOKEN!,
+  startOn: appMentions(),
+  errorMessage: ({ error, runId }) =>
+    error.message.includes("rate limit")
+      ? "I'm getting a lot of requests right now. Try again in a minute."
+      : `Something went wrong answering this. Try again, or share ref ${runId} with support.`,
+});
+```
+
 ## Stopping a turn from the channel
 
 A connector can map an event to a control with `onControl`. Returning `{ kind: "stop" }` while a turn is running aborts it through the run's `stopSignal`, exactly like the browser's stop button: the partial reply posts with `stopped: true` and the event is consumed instead of running as a turn. `linear()` and `slack()` map their stop buttons this way; a custom connector might map a `/stop` command:
@@ -88,7 +114,7 @@ When nothing is running, the event is handled by `inbound` as an ordinary messag
 Two more hooks let a connector mirror the session into a surface that has its own notion of an agent, the way `slack()` does:
 
 - `lifecycle(state, ctx)` reports `working` when a turn starts (and every 50 minutes while it runs), `waiting` when it pauses on a human decision, `idle` when it ends for any reason, and `closed` on `chat.close()`. `ctx.firstTurn` and `ctx.prompt` are there to title a new conversation. Calls are serialized, so an older report never lands after a newer one.
-- `stream(ctx)`, with `delivery: "stream"`, returns a per-turn transport `{ text(delta), progress?(event), end(outcome) }`. The runtime feeds it the reply's markdown deltas and tool progress, then calls `end({ stopped, pending, errorText? })` once. Resolve `{ delivered: true }` when the reply reached the surface, and the runtime does not post it again. Call `ctx.opened(ref)` once the surface has created the stream message: the ref is saved with the session while the turn runs, and if the worker dies mid-stream the next one calls the connector's `endInterruptedStream(ref, ctx)` before it answers, so the old stream does not look like it is still being written.
+- `stream(ctx)`, with `delivery: "stream"`, returns a per-turn transport `{ text(delta), progress?(event), end(outcome) }`. The runtime feeds it the reply's markdown deltas and tool progress, then calls `end({ stopped, pending, errorText? })` once, with the connector's error line as `errorText` when the turn failed. Resolve `{ delivered: true }` when the reply reached the surface, and the runtime does not post it again. Call `ctx.opened(ref)` once the surface has created the stream message: the ref is saved with the session while the turn runs, and if the worker dies mid-stream the next one calls the connector's `endInterruptedStream(ref, ctx)` before it answers, so the old stream does not look like it is still being written.
 
 ## Bound sessions
 

package/docs/webhooks/connect.mdx

@@ -18,8 +18,8 @@ The prompt tells the agent to use the Trigger.dev MCP server (`npx trigger.dev@l
 | --- | --- |
 | `list_webhook_endpoints` | Lists the environment's endpoints, with their URL and whether a secret is set. |
 | `get_webhook_endpoint_details` | Reads one endpoint: URL, subscribers and their filters, secret state, and the setup prompt. |
-| `generate_webhook_secret` | Generates a signing secret and returns it once, for providers where you choose the secret. |
-| `set_webhook_secret` | Stores a secret the provider issued. |
+| `generate_webhook_secret` | Generates a signing secret and returns it once, for providers where you choose the secret. Optionally keeps accepting the old secret (`previousSecretTtlSeconds`). |
+| `set_webhook_secret` | Stores a secret the provider issued. Optionally keeps accepting the old secret (`previousSecretTtlSeconds`). |
 
 Without the MCP server, the same operations are available on the REST API with the environment's secret key:
 
@@ -74,7 +74,18 @@ The verify token answers the URL check. The signing secret verifies event delive
 
 Choose **Rotate signing secret** to replace a provider-supplied secret. For a secret you generate, choose **Regenerate secret**, copy the new value, and update the provider's configuration. Use **Rotate public key** when replacing an asymmetric provider's key.
 
+Both dialogs ask how long to keep accepting the old secret: **Stop immediately**, 1 hour, 24 hours (the default) or 7 days. Until then, deliveries signed with either secret verify, so you can update the provider without failing any. Choose **Stop immediately** if the old secret leaked.
+
+Through the MCP tools or the REST API, pass `previousSecretTtlSeconds` (at most 604800, 7 days). The response's `previousSecretExpiresAt` says when the old secret stops working. Without it, the old secret stops working straight away:
+
+```bash
+curl -X POST "https://api.trigger.dev/api/v1/webhooks/endpoints/github/rotate-secret" \
+  -H "Authorization: Bearer $TRIGGER_SECRET_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"previousSecretTtlSeconds": 3600}'
+```
+
 <Warning>
   Trigger.dev stores credentials encrypted and doesn't display saved values. Copy a generated secret
-  before closing the dialog. Deliveries signed with the old secret fail verification after rotation.
+  before closing the dialog.
 </Warning>

package/docs/webhooks/deliveries.mdx

@@ -81,7 +81,14 @@ Trigger.dev uses the endpoint and idempotency key to deduplicate incoming events
 
 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.
+When the source maps a provider event ID, that ID becomes the key, so the provider's own retries of an event are recognised as duplicates:
+
+| Key | Sources |
+| --- | --- |
+| A header | GitHub (`X-GitHub-Delivery`), Svix and Autumn (`svix-id`), Standard Webhooks, Loops and Granola (`webhook-id`), Linear (`Linear-Delivery`), PagerDuty (`X-Webhook-Id`), Jira (`X-Atlassian-Webhook-Identifier`), Zendesk (`X-Zendesk-Webhook-Invocation-Id`), Attio (`Idempotency-Key`), Shopify (`X-Shopify-Webhook-Id`), Hookdeck (`X-Hookdeck-Eventid`, or `<prefix>-eventid` with a custom header prefix) |
+| A body field | Stripe, Notion, Vercel, Intercom, WorkOS, Metronome, Mux, Langfuse and Plain (`id`), Square, Slack and Typeform (`event_id`), Firecrawl (`webhookId`) |
+
+The other named sources (Zoom, Calendly, Sentry, DocuSign, ElevenLabs, Vapi, Retell, Tailscale, Infisical, PlanetScale, Supabase, Discord) use the fallback below.
 
 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.
 

package/docs/webhooks/filters.mdx

@@ -27,7 +27,36 @@ export const largePayments = webhook({
 
 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.
+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. A filter built at runtime (typed as `string` rather than a string literal) skips the compile-time check, and is validated when the endpoint is deployed.
+
+## Narrow a union event
+
+When the endpoint's event is a union, such as `webhooks.stripe<Stripe.Event>()`, an `event.<field> == '<value>'` clause selects the members whose field can hold that value. The rest of that `&&` chain is checked against those members, and the handler's `event` has their type:
+
+```ts /trigger/checkouts.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+import type Stripe from "stripe";
+
+export const stripe = webhooks.endpoint.define({
+  id: "stripe",
+  source: webhooks.stripe<Stripe.Event>(),
+});
+
+export const checkouts = webhook({
+  id: "checkouts",
+  endpoint: stripe,
+  filter: "event.type == 'checkout.session.completed' && event.data.object.amount_total >= 100",
+  onEvent: async ({ event }) => {
+    const session: Stripe.Checkout.Session = event.data.object; // no cast needed
+    console.log("Checkout completed", session.id);
+  },
+});
+```
+
+- `in [...]` selects the members for any listed value, and `||` gives the union of its branches. Parentheses group branches as usual.
+- `!=`, `not in`, numeric comparisons, string operators, and `any`/`all` don't narrow. Neither do `null`, `'null'`, or `0`, because the server's `==` also matches a null field for those values.
+- Without a type clause, a field that only some members have is accepted: an event without it never matches.
+- The narrowed type also applies to the task's trigger payload, a `chat.event` action's `event` and `key`, channel connector callbacks, and a waiter's event. A filter built at runtime doesn't narrow.
 
 ## Check the result
 
@@ -65,6 +94,8 @@ Paths must have non-empty segments. `event.data.amount` is valid; `event.`, `eve
 
 Values are strings in single quotes (`'created'`), numbers (`10000`), booleans (`true`), or `null`. Use a list of these values with `in` and `not in`.
 
+A `null` value checks presence. `event.issue.pull_request != null` matches events that have the field, and `== null` matches events where it is missing or `null`. It works on any field, including fields your event type marks as required, because a missing field compares equal to `null`.
+
 ### Comparing two fields
 
 Equality and comparison operators also accept a field path on the right-hand side:
@@ -81,9 +112,15 @@ event.billing.country == event.shipping.country
 event.items any ( quantity > 0 )
 ```
 
+When the payload itself is an array, as with providers that batch several events into one request (Tailscale, for example), quantify over `event`:
+
+```text Filter expression
+event any ( type == 'nodeCreated' )
+```
+
 ### 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.
+Separate paths, operators, and values with one space. Parentheses may touch what they enclose, 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
 

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

@@ -37,7 +37,7 @@ Out of the box, `slack()` posts Approve and Deny buttons for any pending no-`exe
 ```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 { appMentions, slack, webhookSource } from "@trigger.dev/slack";
 import { tool } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { z } from "zod";
@@ -56,7 +56,14 @@ const requestApproval = tool({
 
 export const supportAgent = chat.agent({
   id: "support-agent",
-  channels: [slack({ id: "support-slack", endpoint: slackEvents, token: process.env.SLACK_BOT_TOKEN! })],
+  channels: [
+    slack({
+      id: "support-slack",
+      endpoint: slackEvents,
+      token: process.env.SLACK_BOT_TOKEN!,
+      startOn: appMentions(),
+    }),
+  ],
   tools: { requestApproval },
   run: async ({ messages, tools, streamText }) =>
     streamText({
@@ -115,7 +122,9 @@ chat.channels.custom({
     text: `Approve: ${pending[0].input.action}?`,
     buttons: pending.map((c) => [`${c.toolCallId}:yes`, `${c.toolCallId}:no`]),
   }),
+  // called for every delivery: return null for anything that isn't one of these button clicks
   onInteraction: (e) => {
+    if (typeof e.buttonValue !== "string" || !e.buttonValue.includes(":")) return null;
     const [toolCallId, choice] = e.buttonValue.split(":");
     return { toolCallId, output: { approved: choice === "yes" } };
   },

package/docs/webhooks/linear.mdx

@@ -44,7 +44,7 @@ The `run()` loop is the same one a browser chat or a Slack thread uses. Verifica
 
 ## 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.
+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 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).
 
@@ -63,7 +63,7 @@ linear({ id: "linear", endpoint: linearEvents, token, context: { guidance: false
 | 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` |
+| The turn fails | An `error` saying "Something went wrong answering this. Try again." (`errorMessage` changes it) |
 | 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)) |
@@ -164,14 +164,15 @@ The first Linear turn binds the session to the agent session ([bound sessions](/
 | `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. |
+| `filter` | filter string | Extra [filter](/webhooks/filters), composed with the built-in agent-session guard. Checked against the endpoint's event type, like `webhook()`'s `filter`. |
+| `startOn` | filter string | Only start a session when the event matches. Existing sessions always resume. Checked against the endpoint's event type. |
 | `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. |
+| `errorMessage` | `string \| (ctx) => string` | The error activity's text when a turn fails, fixed or built from the failure ([details](/webhooks/channels#when-a-turn-fails)). Default "Something went wrong answering this. Try again." |
 | `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. |

package/docs/webhooks/overview.mdx

@@ -59,6 +59,22 @@ Each subscriber has its own [filter](/webhooks/filters), so one delivery can rea
 | `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. |
 
+`webhook()` also takes the options a [task](/tasks/overview) does, such as `queue`, `concurrency`, `machine`, `retry`, `maxDuration` and the lifecycle hooks. For example, to handle one delivery at a time:
+
+```ts
+export const orders = webhook({
+  id: "stripe-orders",
+  endpoint: stripe,
+  queue: { concurrencyLimit: 1 },
+  retry: { maxAttempts: 5 },
+  onEvent: async ({ event }) => {
+    // ...
+  },
+});
+```
+
+The limit covers every delivery the task handles. To process each customer's events in order while different customers run in parallel, route them to an agent with [session routing](/webhooks/session-routing): deliveries with the same key land in one session and are handled one after another.
+
 `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

package/docs/webhooks/session-routing.mdx

@@ -23,6 +23,8 @@ export const orderEvents = chat.event({
   endpoint: stripe,
   // one session per customer
   key: "{event.data.object.customer}",
+  // invoices always carry a customer; events without one would have no session to go to
+  filter: "event.type startsWith 'invoice.'",
   type: "order.event",
 });
 ```
@@ -81,7 +83,14 @@ When the same session is also a [channel](/webhooks/channels) conversation (a Sl
 ```ts
 export const orderAgent = chat.agent({
   id: "order-agent",
-  channels: [slack({ id: "support-slack", endpoint: slackEvents, token: process.env.SLACK_BOT_TOKEN! })],
+  channels: [
+    slack({
+      id: "support-slack",
+      endpoint: slackEvents,
+      token: process.env.SLACK_BOT_TOKEN!,
+      startOn: appMentions(),
+    }),
+  ],
   events: [orderEvents],
   onAction: async ({ action }) => {
     if (action.type === "order.event") {
@@ -113,7 +122,7 @@ A bound turn posts the final answer as a fresh message in the thread (no placeho
 
 Listing a descriptor on an agent subscribes that agent to the descriptor's endpoint, with the subscriber id `agentId:eventId`. If two agents list the same descriptor, the endpoint has two subscribers and every delivery goes to both, on the one URL the provider already knows.
 
-A session belongs to the agent that created it. When two agents compute the same key, the second agent's delivery to that session fails with an error naming the owner, so give each agent a key that can't collide, for example by prefixing `{webhook.id}` or a constant.
+A session belongs to the agent that created it. When two agents compute the same key, the second agent's delivery to that session fails with an error naming the owner. Both agents see the same endpoint, so a `{webhook.*}` placeholder resolves the same for each and can't separate them. Give each agent its own descriptor with a constant prefix in the key instead, for example `"billing-{event.data.object.customer}"` and `"support-{event.data.object.customer}"`.
 
 An exported `chat.event` that no agent lists routes nothing. `trigger dev` warns about it (it is not an error, since declaring the descriptor before wiring the agent is a normal step), so wire it onto an agent once you are ready.